{"openapi":"3.1.0","info":{"title":"Dealboard API","version":"1.0.0","description":"The public REST API for Dealboard — programmatically read and\nwrite your workspace data. Built for humans and AI agents.\n\n**Authentication.** Send your API key as `Authorization: Bearer dlb_live_…`.\nCreate one in Workspace Settings → API Keys.\n\n**Conventions.** Money is in cents + currency. Timestamps are ISO 8601 UTC.\nIDs are raw UUIDs. Lists are cursor-paginated.\n\n**Idempotency.** Mutating requests accept an `Idempotency-Key` header — replays\nreturn the original response without re-executing.\n\n**Rate limit.** 600 requests/minute/key. Exceeding returns 429 + `Retry-After`.","contact":{"name":"Dealboard","email":"support@getdealboard.com","url":"https://getdealboard.com/developers"}},"servers":[{"url":"https://app.getdealboard.com","description":"Production"}],"security":[{"BearerApiKey":[]}],"components":{"securitySchemes":{"BearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"dlb_live_<43-char-base62>","description":"API keys are workspace-scoped and inherit the creator's role. Generate in Workspace Settings → API Keys."}},"schemas":{"ErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["type","code","message","request_id"],"properties":{"type":{"type":"string","description":"Coarse machine-readable category.","enum":["authentication_error","permission_error","invalid_request_error","not_found","rate_limit_error","conflict_error","unsupported_media_type","method_not_allowed","api_error"]},"code":{"type":"string","description":"Finer-grained error code."},"message":{"type":"string","description":"Human-readable English explanation."},"request_id":{"type":"string","description":"The Dealboard-Request-Id assigned to this request. Quote this when filing a bug."}}}}},"Deal":{"type":"object","required":["id","boardId","name","company","amountCents","currency","stage","ownerId","ownerName","labels","primaryContact","keyTerms","createdAt","updatedAt","stageEnteredAt","proposalSentAt","wonAt","deadAt"],"properties":{"id":{"type":"string","format":"uuid"},"boardId":{"type":"string","format":"uuid"},"name":{"type":"string"},"company":{"type":["string","null"]},"amountCents":{"type":["integer","null"],"description":"Deal value in minor currency units (cents). No floats."},"currency":{"type":"string","enum":["USD","EUR","GBP","CAD","AUD","JPY","INR"]},"stage":{"type":"string","enum":["new_lead","meeting_scheduled","in_discussion","proposal_sent","contract_in_legal","contract_redlines","won","dead"]},"ownerId":{"type":"string","format":"uuid"},"ownerName":{"type":["string","null"]},"labels":{"type":"array","items":{"type":"string"}},"primaryContact":{"type":"object","required":["name","title","email","phone","linkedin"],"properties":{"name":{"type":["string","null"]},"title":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"linkedin":{"type":["string","null"]}}},"keyTerms":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"stageEnteredAt":{"type":"string","format":"date-time"},"proposalSentAt":{"type":["string","null"],"format":"date-time"},"wonAt":{"type":["string","null"],"format":"date-time"},"deadAt":{"type":["string","null"],"format":"date-time"}}},"Board":{"type":"object","required":["id","teamId","name","currency","defaultDealAmountCents","stageProbabilities","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"teamId":{"type":"string","format":"uuid"},"name":{"type":"string"},"currency":{"type":"string","enum":["USD","EUR","GBP","CAD","AUD","JPY","INR"]},"defaultDealAmountCents":{"type":"integer"},"stageProbabilities":{"type":"object","additionalProperties":{"type":"number","minimum":0,"maximum":100}},"createdAt":{"type":"string","format":"date-time"}}},"Note":{"type":"object","required":["id","dealId","authorId","kind","contentText","contentJson","systemEventType","systemEventData","createdAt","editedAt"],"properties":{"id":{"type":"string","format":"uuid"},"dealId":{"type":"string","format":"uuid"},"authorId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["manual","system_event"]},"contentText":{"type":["string","null"]},"contentJson":{"description":"Tiptap document JSON for manual notes; null for system events."},"systemEventType":{"type":["string","null"]},"systemEventData":{},"createdAt":{"type":"string","format":"date-time"},"editedAt":{"type":["string","null"],"format":"date-time"}}},"Webhook":{"type":"object","required":["id","boardId","label","urlFingerprint","provider","events","stageFilter","active","createdAt","lastDeliveredAt","lastError"],"properties":{"id":{"type":"string","format":"uuid"},"boardId":{"type":"string","format":"uuid"},"label":{"type":["string","null"]},"urlFingerprint":{"type":"string","description":"Last 4 characters of the URL. The URL itself is a secret and is never returned."},"provider":{"type":"string","enum":["slack","teams","discord","generic"]},"events":{"type":"array","items":{"type":"string","enum":["deal.created","deal.stage_changed","deal.won"]}},"stageFilter":{"type":"array","items":{"type":"string","enum":["new_lead","meeting_scheduled","in_discussion","proposal_sent","contract_in_legal","contract_redlines","won","dead"]}},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"lastDeliveredAt":{"type":["string","null"],"format":"date-time"},"lastError":{"type":["string","null"]}}},"DealList":{"type":"object","required":["data","hasMore","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Deal"}},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"],"description":"Pass as `?cursor=` on the next request to fetch the next page."}}},"BoardList":{"type":"object","required":["data","hasMore","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Board"}},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"],"description":"Pass as `?cursor=` on the next request to fetch the next page."}}},"NoteList":{"type":"object","required":["data","hasMore","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Note"}},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"],"description":"Pass as `?cursor=` on the next request to fetch the next page."}}},"WebhookList":{"type":"object","required":["data","hasMore","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"],"description":"Pass as `?cursor=` on the next request to fetch the next page."}}},"Me":{"type":"object","required":["user","workspace","apiKey"],"properties":{"user":{"type":"object","required":["id","email","name"],"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"name":{"type":["string","null"]}}},"workspace":{"type":"object","required":["id","name","plan"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"plan":{"type":"string","enum":["free","standard"]}}},"apiKey":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}}}}},"paths":{"/v1/me":{"get":{"summary":"Verify your API key","description":"Returns the calling user, their workspace, and the key in use. The fastest way to confirm a key works.","tags":["Auth"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/deals":{"get":{"summary":"List deals","tags":["Deals"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Max number of items per page (1-100)."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from a previous response's `nextCursor`."},{"name":"boardId","in":"query","schema":{"type":"string","format":"uuid"},"description":"Filter to one board."},{"name":"stage","in":"query","schema":{"type":"string","enum":["new_lead","meeting_scheduled","in_discussion","proposal_sent","contract_in_legal","contract_redlines","won","dead"]},"description":"Filter to one stage."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DealList"}}}},"400":{"description":"Invalid query parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Create a deal","tags":["Deals"],"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string"},"description":"Optional client-chosen string. If the same key is sent twice within 24h with the same body, the original response is replayed."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["boardId","name"],"properties":{"boardId":{"type":"string","format":"uuid"},"name":{"type":"string","maxLength":200},"company":{"type":["string","null"]},"amountCents":{"type":["integer","null"],"minimum":0},"stage":{"type":"string","enum":["new_lead","meeting_scheduled","in_discussion","proposal_sent","contract_in_legal","contract_redlines","won","dead"]},"ownerId":{"type":"string","format":"uuid","description":"Defaults to the API key's creator."},"labels":{"type":"array","items":{"type":"string"}},"primaryContactName":{"type":["string","null"]},"primaryContactTitle":{"type":["string","null"]},"primaryContactEmail":{"type":["string","null"]},"primaryContactPhone":{"type":["string","null"]},"primaryContactLinkedin":{"type":["string","null"]},"keyTerms":{"type":["string","null"]}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deal"}}}},"400":{"description":"Invalid input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Board not found in your workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Idempotency-Key reused with a different body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/deals/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get one deal","tags":["Deals"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deal"}}}},"404":{"description":"Deal not found in your workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"summary":"Update a deal","tags":["Deals"],"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string"},"description":"Optional client-chosen string. If the same key is sent twice within 24h with the same body, the original response is replayed."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"All fields are optional; only the ones you send are updated.","properties":{"name":{"type":"string","maxLength":200},"company":{"type":["string","null"]},"amountCents":{"type":["integer","null"],"minimum":0},"stage":{"type":"string","enum":["new_lead","meeting_scheduled","in_discussion","proposal_sent","contract_in_legal","contract_redlines","won","dead"]},"ownerId":{"type":"string","format":"uuid"},"labels":{"type":"array","items":{"type":"string"}},"primaryContactName":{"type":["string","null"]},"primaryContactTitle":{"type":["string","null"]},"primaryContactEmail":{"type":["string","null"]},"primaryContactPhone":{"type":["string","null"]},"primaryContactLinkedin":{"type":["string","null"]},"keyTerms":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deal"}}}},"400":{"description":"Invalid input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Deal not found in your workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Delete a deal","description":"Soft delete. Deals are purged after a 30-day grace period.","tags":["Deals"],"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string"},"description":"Optional client-chosen string. If the same key is sent twice within 24h with the same body, the original response is replayed."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["id","deleted"],"properties":{"id":{"type":"string"},"deleted":{"type":"boolean"}}}}}},"404":{"description":"Deal not found in your workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/deals/{id}/move":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Move a deal to a new stage","description":"Stamps wonAt/deadAt/proposalSentAt automatically as appropriate. Fires `deal.stage_changed` (and `deal.won` when applicable) on subscribed webhooks.","tags":["Deals"],"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string"},"description":"Optional client-chosen string. If the same key is sent twice within 24h with the same body, the original response is replayed."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["toStage"],"properties":{"toStage":{"type":"string","enum":["new_lead","meeting_scheduled","in_discussion","proposal_sent","contract_in_legal","contract_redlines","won","dead"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deal"}}}},"404":{"description":"Deal not found in your workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/deals/{id}/notes":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"List manual notes on a deal","tags":["Notes"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Max number of items per page (1-100)."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from a previous response's `nextCursor`."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoteList"}}}}}},"post":{"summary":"Add a manual note","tags":["Notes"],"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string"},"description":"Optional client-chosen string. If the same key is sent twice within 24h with the same body, the original response is replayed."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["contentText"],"properties":{"contentText":{"type":"string","maxLength":20000}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Note"}}}}}}},"/v1/deals/{id}/activity":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"List notes + system events (full activity feed)","tags":["Notes"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Max number of items per page (1-100)."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from a previous response's `nextCursor`."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoteList"}}}}}}},"/v1/notes/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"summary":"Edit a manual note","tags":["Notes"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["contentText"],"properties":{"contentText":{"type":"string","maxLength":20000}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Note"}}}},"404":{"description":"Note not found in your workspace, or is a system event (not editable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Delete a manual note","tags":["Notes"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["id","deleted"],"properties":{"id":{"type":"string"},"deleted":{"type":"boolean"}}}}}},"404":{"description":"Note not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/boards":{"get":{"summary":"List boards","tags":["Boards"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Max number of items per page (1-100)."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from a previous response's `nextCursor`."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardList"}}}}}},"post":{"summary":"Create a board (admin only)","tags":["Boards"],"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string"},"description":"Optional client-chosen string. If the same key is sent twice within 24h with the same body, the original response is replayed."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":80},"currency":{"type":"string","enum":["USD","EUR","GBP","CAD","AUD","JPY","INR"]}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Board"}}}},"403":{"description":"Admin role required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/boards/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get one board","tags":["Boards"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Board"}}}},"404":{"description":"Board not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"summary":"Update a board (admin only)","tags":["Boards"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":80},"currency":{"type":"string","enum":["USD","EUR","GBP","CAD","AUD","JPY","INR"]},"defaultDealAmountCents":{"type":"integer","minimum":0}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Board"}}}},"403":{"description":"Admin role required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/webhooks":{"get":{"summary":"List webhook subscriptions","tags":["Webhooks"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Max number of items per page (1-100)."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from a previous response's `nextCursor`."},{"name":"boardId","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookList"}}}}}},"post":{"summary":"Create a webhook subscription (admin only)","description":"For `generic` provider webhooks, the response includes a one-time `signingSecret` — capture it; the secret cannot be retrieved later.","tags":["Webhooks"],"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string"},"description":"Optional client-chosen string. If the same key is sent twice within 24h with the same body, the original response is replayed."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["boardId","url","events"],"properties":{"boardId":{"type":"string","format":"uuid"},"url":{"type":"string","maxLength":2000},"label":{"type":["string","null"],"maxLength":80},"events":{"type":"array","minItems":1,"items":{"type":"string","enum":["deal.created","deal.stage_changed","deal.won"]}},"stageFilter":{"type":"array","items":{"type":"string","enum":["new_lead","meeting_scheduled","in_discussion","proposal_sent","contract_in_legal","contract_redlines","won","dead"]}}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Webhook"},{"type":"object","properties":{"signingSecret":{"type":["string","null"],"description":"Non-null only for `generic` provider. Shown exactly once."}}}]}}}},"400":{"description":"Invalid URL or input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Admin role required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/webhooks/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"delete":{"summary":"Delete a webhook subscription (admin only)","tags":["Webhooks"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["id","deleted"],"properties":{"id":{"type":"string"},"deleted":{"type":"boolean"}}}}}},"403":{"description":"Admin role required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Webhook not found in your workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}