{ "openapi": "3.1.0", "info": { "title": "Digital Agency Tools API", "version": "1.0.0", "description": "The Digital Agency Tools API gives you programmatic access to your business: contacts and deals, projects and tasks, meetings and bookings, products, invoices, proposals, tickets, forms and more.\n\n**Base URL:** `https://api.digitalagency.dev/v1` \n**Auth:** `Authorization: Bearer ` — create keys in Settings → Developers. \n**Format:** JSON in, JSON out. Every success is `{\"data\": …, \"meta\": {\"request_id\"}}`; every error is `{\"error\": {\"type\", \"message\"}, \"meta\"}`.\n\nGuides — quickstart, scopes, errors, pagination, rate limits, idempotency and webhooks — are at [https://docs.digitalagency.dev/api](https://docs.digitalagency.dev/api).", "contact": { "name": "Support", "url": "https://docs.digitalagency.dev/help" } }, "servers": [ { "url": "https://api.digitalagency.dev/v1", "description": "Production" } ], "security": [ { "ApiKey": [] } ], "tags": [ { "name": "Account", "description": "Check connectivity, inspect the key you are using, and read or update the business it belongs to." }, { "name": "Contacts", "description": "Contacts are your clients and prospects. Projects, invoices, proposals and tickets all point at a contact.\n\nA *deal* is not a separate object — it is a contact with a pipeline status (`crm_status`). See **Deals**." }, { "name": "Deals", "description": "A **deal** is a contact on your sales pipeline. There is no separate deal object: the deal's id *is* the contact id, and its `status` is the contact's pipeline status.\n\n- Move a deal with `PATCH /deals/{id}/status` — the same action as dragging a card on the panel's Deals board.\n- Every move emits `deal.status_changed`; a move to `closed_won` also emits `deal.won`.\n- Pipeline columns are managed with `/deal-statuses`." }, { "name": "Projects", "description": "Client projects and everything hanging off them: milestones, deliverables, scope, requests to the client, the people who can see the project, client update emails and the client portal.\n\n- Every project belongs to a **contact** (`client_id`).\n- Tasks live under **Tasks** (`GET /tasks?project_id=`).\n- A client approving a deliverable in the portal emits `deliverable.approved`.\n- Portal links are shown **once**, when created or regenerated: only a hash is stored." }, { "name": "Tasks", "description": "Tasks belong to a project and move through the business's own **task statuses** (the board columns).\n\n- `is_done` is true when the status is one the business marks as finished.\n- Moving a task into such a status stamps `completed_at` and emits `task.completed` (as well as `task.updated`).\n- Schedule a task on the planner with `POST /tasks/{id}/schedule` (see **Planner**)." }, { "name": "Planner", "description": "The day planner: tasks placed on the calendar, alongside meetings and the business's connected Google calendars.\n\n- `GET /planner/unscheduled` is the backlog — open tasks not yet on the calendar.\n- `POST /tasks/{id}/schedule` places a task; `DELETE` puts it back in the backlog.\n- When Google Calendar is connected, scheduling also creates (and unscheduling removes) the matching Google event." }, { "name": "Meetings & bookings", "description": "Your calendar has two kinds of appointment.\n\n* A **meeting** is arranged by you (in the panel or through this API): `/meetings/{id}`.\n* A **booking** is made by a customer on your public booking page, against a product: `/bookings/{id}`.\n\nTheir ids are separate sequences, so meeting 12 and booking 12 are different things. `GET /meetings` lists both, merged by date: every row carries `kind` (`meeting` or `booking`) and `id`, and `path` tells you which resource to open.\n\nBooking payments (links, reminders, cash, refunds) are under `/bookings/{id}/…`. Customers create bookings on the booking page, not through the API: listen for `booking.created` and `booking.paid`." }, { "name": "Products", "description": "Products are the services customers book on your booking page; invoice lines can be priced from them. Group them with **categories**, and sell several together as a **package**.\n\nA product books into your business hours unless its `schedule_mode` is `custom_schedule`; then its own **schedules** (one-off dates or weekly slots) apply. Check free slots with `GET /availability`.\n\nCover photos and galleries are uploaded in the panel: v1 has no file uploads." }, { "name": "Coupons", "description": "Discount codes customers enter on your booking page — the coupons on the panel's **Coupons** page.\n\nA coupon that has been used cannot be erased: DELETE deactivates it, so its redemptions stay on record." }, { "name": "Invoices", "description": "Invoices to your clients. An invoice starts as a **draft** you can edit; **issue** gives it a number, freezes it and (by default) emails it with a pay link; payments received move it to **paid**. An issued invoice is never edited: **void** it and raise another.\n\nAll amounts are decimals in the invoice's `currency` (e.g. `199.99`). Totals are worked out by the server, VAT per line and rounded per line." }, { "name": "Proposals", "description": "Proposals (quotes) you send to a client. Build one as a **draft**, then `send` it: the client gets a private link where they accept or decline.\n\nAccepting creates a project and client portal automatically (or call `convert`). Money is returned as decimals in the proposal's currency.\n\nThe client link is returned **once**, by `send` and `regenerate-link` — it is stored only as a hash." }, { "name": "Discoveries", "description": "Discovery turns raw input — call notes, an intake form, an email thread — into a structured brief, research notes and questions for the client, then hands it to the proposal builder.\n\nThe AI steps are optional; everything else works without an AI provider." }, { "name": "Tickets", "description": "Support tickets from clients — opened in the panel, by email, over WhatsApp, through the public support form or by this API. Each ticket has a thread of replies; internal notes are replies only your team sees." }, { "name": "Forms", "description": "Intake forms your clients and leads fill in at `/intake/{slug}`, and what they sent. Build and edit forms in the panel; the API reads them.\n\nSubscribe to the `form.submitted` webhook to hear about new submissions as they arrive." }, { "name": "Newsletter", "description": "Your newsletter list and the campaigns you send to it.\n\nA campaign is written as a **draft** and sent with `POST /campaigns/{id}/send`, which emails every active subscriber. Removing a subscriber keeps the row as `inactive`; subscribing the same address again reactivates it." }, { "name": "Staff", "description": "The people who can sign in to this business, and their role: **owner**, **admin**, **member** or **client** (read-only).\n\nListing needs a `read` key; adding, changing and removing people needs an `admin` key." }, { "name": "Notifications", "description": "The in-app notification feed — what the bell in the panel shows: proposals opened and accepted, approvals in the portal, overdue invoices, new tickets.\n\nRead state is shared by the whole business: marking one read here marks it read for everyone. Notifications addressed to one person are not visible to an API key." }, { "name": "Developers", "description": "Manage API keys and webhook endpoints programmatically. Everything here needs an `admin` key.\n\nA new key or endpoint secret is returned **once**, in the create response — store it then." } ], "paths": { "/api-keys": { "get": { "tags": [ "Developers" ], "summary": "List API keys", "operationId": "devKeysList", "description": "Scope: `admin`.", "security": [ { "ApiKey": [] } ], "x-scope": "admin", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Developers" ], "summary": "Create an API key", "operationId": "devKeysCreate", "description": "Scope: `admin`.", "security": [ { "ApiKey": [] } ], "x-scope": "admin", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ApiKeyCreated" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api-keys/{id}": { "delete": { "tags": [ "Developers" ], "summary": "Revoke an API key", "operationId": "devKeysRevoke", "description": "Takes effect on the next request. You cannot revoke the key making this call.\n\nScope: `admin`.", "security": [ { "ApiKey": [] } ], "x-scope": "admin", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/availability": { "get": { "tags": [ "Meetings & bookings" ], "summary": "Check a product's free slots", "operationId": "availabilityGet", "description": "The slots of one product on one day, as the public booking page offers them.\n\nScope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "product_id", "in": "query", "required": false, "description": "Required. One of your products.", "schema": { "type": "integer" } }, { "name": "date", "in": "query", "required": false, "description": "Required. YYYY-MM-DD.", "schema": { "type": "string" } }, { "name": "timezone", "in": "query", "required": false, "description": "Optional IANA zone of the customer, e.g. Europe/Dublin.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Availability" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/bookings": { "get": { "tags": [ "Meetings & bookings" ], "summary": "List bookings", "operationId": "bookingsList", "description": "Scope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "YYYY-MM-DD; on or after this day.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "YYYY-MM-DD; on or before this day.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "pending, confirmed, completed, cancelled or no_show.", "schema": { "type": "string" } }, { "name": "payment_status", "in": "query", "required": false, "description": "e.g. paid, free, pending.", "schema": { "type": "string" } }, { "name": "product_id", "in": "query", "required": false, "description": "Bookings of this product.", "schema": { "type": "integer" } }, { "name": "contact_id", "in": "query", "required": false, "description": "Bookings made with this contact's email.", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "Search customer name and email.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "ISO 8601; only bookings changed at or after this time.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`starts_at`, `created_at` (default `-starts_at`) or `updated_at`; prefix `-` for descending.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Booking" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/bookings/{id}": { "get": { "tags": [ "Meetings & bookings" ], "summary": "Retrieve a booking", "operationId": "bookingsGet", "description": "Scope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Booking" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/bookings/{id}/cash-payment": { "post": { "tags": [ "Meetings & bookings" ], "summary": "Record a cash payment", "operationId": "bookingsCashPayment", "description": "Raises a paid receipt (an invoice) for the amount. `booking.paid` is sent when it clears the balance.\n\nScope: `write`.\n\nEmits: `booking.paid`, `invoice.issued`, `invoice.paid`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingCashPaymentInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BookingCashPaymentResult" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/bookings/{id}/payment-link": { "post": { "tags": [ "Meetings & bookings" ], "summary": "Create a payment link for the balance", "operationId": "bookingsPaymentLink", "description": "A card payment link (Stripe) for the outstanding balance. Refused with `invalid_request` when nothing is owed.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BookingPaymentLink" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/bookings/{id}/payment-reminder": { "post": { "tags": [ "Meetings & bookings" ], "summary": "Email a balance reminder", "operationId": "bookingsPaymentReminder", "description": "Emails the customer what is still owed. Refused with `invalid_request` when nothing is owed.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BookingReminderResult" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/bookings/{id}/refund": { "post": { "tags": [ "Meetings & bookings" ], "summary": "Refund a booking", "operationId": "bookingsRefund", "description": "Refunds (part of) the booking's own card payment through Stripe.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingRefundInput" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BookingRefundResult" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/bookings/{id}/status": { "patch": { "tags": [ "Meetings & bookings" ], "summary": "Set a booking's status", "operationId": "bookingsStatus", "description": "Cancelling also removes the Google Calendar event and the Zoom meeting.\n\nScope: `write`.\n\nEmits: `meeting.cancelled`, `meeting.completed`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingStatusInput" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Booking" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/business": { "get": { "tags": [ "Account" ], "summary": "Retrieve the business", "operationId": "metaBusiness", "description": "Scope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Business" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "tags": [ "Account" ], "summary": "Update the business", "operationId": "metaBusinessUpdate", "description": "Changes the business's public name and contact details. Branding, payments and integrations stay in the panel.\n\nScope: `admin`.", "security": [ { "ApiKey": [] } ], "x-scope": "admin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessInput" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Business" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/campaigns": { "get": { "tags": [ "Newsletter" ], "summary": "List campaigns", "operationId": "campaignsList", "description": "Scope: `read`. Needs the `newsletter` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "x-feature": "newsletter", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "`draft` or `sent`.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "ISO 8601; only campaigns changed at or after this time.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`created_at`, `updated_at` (default `-updated_at`) or `sent_at`; prefix `-` for descending.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Campaign" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Newsletter" ], "summary": "Create a draft campaign", "operationId": "campaignsCreate", "description": "Scope: `write`. Needs the `newsletter` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "newsletter", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Campaign" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/campaigns/{id}": { "get": { "tags": [ "Newsletter" ], "summary": "Retrieve a campaign", "operationId": "campaignsGet", "description": "Scope: `read`. Needs the `newsletter` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "x-feature": "newsletter", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Campaign" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Newsletter" ], "summary": "Update a draft campaign", "operationId": "campaignsUpdate", "description": "Send only the fields you want to change. A sent campaign cannot be edited.\n\nScope: `write`. Needs the `newsletter` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "newsletter", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignPatch" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Campaign" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/campaigns/{id}/send": { "post": { "tags": [ "Newsletter" ], "summary": "Send a campaign", "operationId": "campaignsSend", "description": "Emails the campaign to every active subscriber now, then marks it `sent`. A campaign is sent once; it needs a title and content.\n\nRefused with `invalid_request` when there are no active subscribers or no email could be sent.\n\nScope: `write`. Needs the `newsletter` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "newsletter", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CampaignSendResult" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/categories": { "get": { "tags": [ "Products" ], "summary": "List product categories", "operationId": "categoriesList", "description": "Scope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "`active` or `inactive`.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductCategory" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Products" ], "summary": "Create a product category", "operationId": "categoriesCreate", "description": "Scope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCategoryInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ProductCategory" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/categories/{id}": { "get": { "tags": [ "Products" ], "summary": "Retrieve a product category", "operationId": "categoriesGet", "description": "Scope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ProductCategory" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Products" ], "summary": "Update a product category", "operationId": "categoriesUpdate", "description": "Scope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCategoryPatch" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ProductCategory" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } }, "delete": { "tags": [ "Products" ], "summary": "Delete a product category", "operationId": "categoriesDelete", "description": "Its products are kept, uncategorised.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/contacts": { "get": { "tags": [ "Contacts" ], "summary": "List contacts", "operationId": "contactsList", "description": "Scope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search name, company and email.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "`client` or `prospect`.", "schema": { "type": "string" } }, { "name": "crm_status", "in": "query", "required": false, "description": "Only contacts in this pipeline status.", "schema": { "type": "string" } }, { "name": "email", "in": "query", "required": false, "description": "Exact email match (case-insensitive).", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "ISO 8601; only contacts changed at or after this time.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`name`, `created_at` (default `-created_at`) or `updated_at`; prefix `-` for descending.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Contacts" ], "summary": "Create a contact", "operationId": "contactsCreate", "description": "Scope: `write`.\n\nEmits: `contact.created`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Contact" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/contacts/{id}": { "get": { "tags": [ "Contacts" ], "summary": "Retrieve a contact", "operationId": "contactsGet", "description": "Scope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Contact" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Contacts" ], "summary": "Update a contact", "operationId": "contactsUpdate", "description": "Send only the fields you want to change.\n\nScope: `write`.\n\nEmits: `contact.updated`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactPatch" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Contact" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } }, "delete": { "tags": [ "Contacts" ], "summary": "Delete a contact", "operationId": "contactsDelete", "description": "Refused with `invalid_request` while the contact still has projects — delete or reassign them first.\n\nScope: `write`.\n\nEmits: `contact.deleted`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/contacts/{id}/notes": { "get": { "tags": [ "Contacts" ], "summary": "List a contact's notes", "operationId": "contactsNotesList", "description": "Scope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactNote" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "Contacts" ], "summary": "Add a note to a contact", "operationId": "contactsNotesCreate", "description": "Scope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactNoteInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ContactNote" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/contacts/{id}/notes/{note_id}": { "delete": { "tags": [ "Contacts" ], "summary": "Delete a contact note", "operationId": "contactsNotesDelete", "description": "Scope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "note_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/coupons": { "get": { "tags": [ "Coupons" ], "summary": "List coupons", "operationId": "couponsList", "description": "Scope: `read`. Needs the `stripe_payments` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "x-feature": "stripe_payments", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search the code.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "`active` or `inactive`.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`code`, `created_at` (default `-created_at`) or `updated_at`; prefix `-` for descending.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "ISO 8601; only coupons changed at or after this time.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Coupon" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Coupons" ], "summary": "Create a coupon", "operationId": "couponsCreate", "description": "Scope: `write`. Needs the `stripe_payments` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "stripe_payments", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Coupon" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/coupons/{id}": { "get": { "tags": [ "Coupons" ], "summary": "Retrieve a coupon", "operationId": "couponsGet", "description": "Scope: `read`. Needs the `stripe_payments` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "x-feature": "stripe_payments", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Coupon" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Coupons" ], "summary": "Update a coupon", "operationId": "couponsUpdate", "description": "Send only the fields you want to change; `product_ids` / `customer_emails`, when sent, replace the list.\n\nScope: `write`. Needs the `stripe_payments` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "stripe_payments", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponPatch" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Coupon" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } }, "delete": { "tags": [ "Coupons" ], "summary": "Delete a coupon", "operationId": "couponsDelete", "description": "A coupon that has been used is deactivated instead, so its redemptions stay on record.\n\nScope: `write`. Needs the `stripe_payments` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "stripe_payments", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/coupons/{id}/usage": { "get": { "tags": [ "Coupons" ], "summary": "A coupon's redemptions", "operationId": "couponsUsage", "description": "Scope: `read`. Needs the `stripe_payments` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "x-feature": "stripe_payments", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CouponUsage" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/deal-statuses": { "get": { "tags": [ "Deals" ], "summary": "List pipeline statuses", "operationId": "dealStatusesList", "description": "The pipeline columns in board order. A business that never customised its pipeline gets the built-in six (lead → closed_lost) saved on first use.\n\nScope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "include_inactive", "in": "query", "required": false, "description": "Include deactivated statuses.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DealStatus" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Deals" ], "summary": "Create a pipeline status", "operationId": "dealStatusesCreate", "description": "Added at the end of the pipeline. `key` must be unique in the business.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealStatusInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/DealStatus" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/deal-statuses/{id}": { "patch": { "tags": [ "Deals" ], "summary": "Update a pipeline status", "operationId": "dealStatusesUpdate", "description": "Change the label, description or colour. The key never changes, so deals stay put.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealStatusPatch" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/DealStatus" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } }, "delete": { "tags": [ "Deals" ], "summary": "Delete a pipeline status", "operationId": "dealStatusesDelete", "description": "Deals in the deleted status move to `lead`. Built-in statuses (`is_default`) cannot be deleted.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/deals": { "get": { "tags": [ "Deals" ], "summary": "List deals", "operationId": "dealsList", "description": "Contacts as pipeline deals. Filter by status to read one column of the board.\n\nScope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Only deals in this pipeline status (alias: `crm_status`).", "schema": { "type": "string" } }, { "name": "crm_status", "in": "query", "required": false, "description": "Same as `status`.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "`client` or `prospect` (the panel board shows prospects).", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Search name, company and email.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "ISO 8601; only deals changed at or after this time.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`name`, `value`, `expected_close_date`, `created_at` (default `-created_at`) or `updated_at`; prefix `-` for descending.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Deal" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/deals/forecast": { "get": { "tags": [ "Deals" ], "summary": "Pipeline forecast", "operationId": "dealsForecast", "description": "Pipeline value grouped by status and by expected close month, plus the service-based revenue forecast shown on the panel's Forecast tab.\n\nScope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "type", "in": "query", "required": false, "description": "`client` or `prospect`; default all.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "YYYY-MM-DD; with `to`, adds a `custom` revenue period.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "YYYY-MM-DD.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/DealForecast" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/deals/{id}": { "get": { "tags": [ "Deals" ], "summary": "Retrieve a deal", "operationId": "dealsGet", "description": "The contact with this id, in its deal shape.\n\nScope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Deal" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/deals/{id}/status": { "patch": { "tags": [ "Deals" ], "summary": "Move a deal to another status", "operationId": "dealsSetStatus", "description": "The same as dragging the card on the Deals board. Moving to the status it is already in is a no-op and emits nothing. `deal.won` is emitted for `closed_won`; the webhook payload carries `previous_status`.\n\nScope: `write`.\n\nEmits: `deal.status_changed`, `deal.won`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealStatusChange" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Deal" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/discoveries": { "get": { "tags": [ "Discoveries" ], "summary": "List discoveries", "operationId": "discoveriesList", "description": "Questions are included when you retrieve one discovery; the list returns `questions: []`.\n\nScope: `read`. Needs the `discover` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "x-feature": "discover", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "One of: intake, researched, questions_ready, meeting_done, brief_ready.", "schema": { "type": "string" } }, { "name": "client_id", "in": "query", "required": false, "description": "Only discoveries for this contact.", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "Search the title.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "ISO 8601; only discoveries changed at or after this time.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`created_at`, `updated_at` (default `-updated_at`) or `title`; prefix `-` for descending.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Discovery" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Discoveries" ], "summary": "Create a discovery", "operationId": "discoveriesCreate", "description": "Scope: `write`. Needs the `discover` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "discover", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoveryInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Discovery" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/discoveries/{id}": { "get": { "tags": [ "Discoveries" ], "summary": "Retrieve a discovery", "operationId": "discoveriesGet", "description": "Scope: `read`. Needs the `discover` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "x-feature": "discover", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Discovery" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Discoveries" ], "summary": "Update a discovery", "operationId": "discoveriesUpdate", "description": "Send only the fields you want to change.\n\nScope: `write`. Needs the `discover` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "discover", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoveryPatch" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Discovery" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } }, "delete": { "tags": [ "Discoveries" ], "summary": "Delete a discovery", "operationId": "discoveriesDelete", "description": "Proposals created from it are kept.\n\nScope: `write`. Needs the `discover` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "discover", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/discoveries/{id}/extract": { "post": { "tags": [ "Discoveries" ], "summary": "Extract a brief with AI", "operationId": "discoveriesExtract", "description": "Reads `raw_input` and writes `brief` and `brief_summary`; an `intake` discovery moves to `researched`. Needs an AI provider: answers 503 `ai_unavailable` when none is configured, or when the provider does not return a usable answer. Each successful call counts towards the business's AI usage.\n\nScope: `write`. Needs the `discover` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "discover", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Discovery" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/discoveries/{id}/proposal": { "post": { "tags": [ "Discoveries" ], "summary": "Create a proposal from the brief", "operationId": "discoveriesProposal", "description": "A draft proposal linked to this discovery, with the intro and a Scope section pre-filled from the brief. Also needs the `proposals` feature.\n\nScope: `write`. Needs the `discover` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "discover", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoveryProposalInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Proposal" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/discoveries/{id}/questions": { "post": { "tags": [ "Discoveries" ], "summary": "Draft client questions with AI", "operationId": "discoveriesQuestions", "description": "Replaces the questions and moves the discovery to `questions_ready`. Needs an AI provider: answers 503 `ai_unavailable` when none is configured, or when the provider does not return a usable answer. Each successful call counts towards the business's AI usage.\n\nScope: `write`. Needs the `discover` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "discover", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Discovery" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/discoveries/{id}/research": { "post": { "tags": [ "Discoveries" ], "summary": "Write research notes with AI", "operationId": "discoveriesResearch", "description": "Writes `research_notes` from the brief. Needs an AI provider: answers 503 `ai_unavailable` when none is configured, or when the provider does not return a usable answer. Each successful call counts towards the business's AI usage.\n\nScope: `write`. Needs the `discover` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "discover", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Discovery" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/events": { "get": { "tags": [ "Developers" ], "summary": "List webhook event types", "operationId": "devEvents", "description": "Scope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventType" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/forms": { "get": { "tags": [ "Forms" ], "summary": "List forms", "operationId": "formsList", "description": "Scope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "active", "in": "query", "required": false, "description": "Only active (`true`) or inactive (`false`) forms.", "schema": { "type": "boolean" } }, { "name": "updated_since", "in": "query", "required": false, "description": "ISO 8601; only forms changed at or after this time.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`created_at` (default `-created_at`), `updated_at` or `name`; prefix `-` for descending.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FormSummary" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/forms/{id}": { "get": { "tags": [ "Forms" ], "summary": "Retrieve a form", "operationId": "formsGet", "description": "Includes the field definitions.\n\nScope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Form" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/forms/{id}/submissions": { "get": { "tags": [ "Forms" ], "summary": "List a form's submissions", "operationId": "formsSubmissionsList", "description": "Scope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "required": false, "description": "`draft`, `submitted`, `processed` or `archived`.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`submitted_at` (default `-submitted_at`); prefix `-` for descending.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FormSubmission" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/invoices": { "get": { "tags": [ "Invoices" ], "summary": "List invoices", "operationId": "invoicesList", "description": "Scope: `read`. Needs the `stripe_payments` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "x-feature": "stripe_payments", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "`draft`, `open`, `paid`, `void`, `uncollectible`, or `overdue` (open and past due).", "schema": { "type": "string" } }, { "name": "client_id", "in": "query", "required": false, "description": "Invoices to this contact.", "schema": { "type": "integer" } }, { "name": "from", "in": "query", "required": false, "description": "YYYY-MM-DD; invoice date on or after.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "YYYY-MM-DD; invoice date on or before.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Search number, client name, company, email and memo.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "ISO 8601; only invoices changed at or after this time.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`invoice_date` (default `-invoice_date`), `due_date`, `total`, `created_at` or `updated_at`; prefix `-` for descending.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Invoices" ], "summary": "Create a draft invoice", "operationId": "invoicesCreate", "description": "Scope: `write`. Needs the `stripe_payments` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "stripe_payments", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Invoice" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/invoices/{id}": { "get": { "tags": [ "Invoices" ], "summary": "Retrieve an invoice", "operationId": "invoicesGet", "description": "Scope: `read`. Needs the `stripe_payments` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "x-feature": "stripe_payments", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Invoice" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Invoices" ], "summary": "Update a draft invoice", "operationId": "invoicesUpdate", "description": "Drafts only; an issued invoice is refused with `invalid_request`.\n\nScope: `write`. Needs the `stripe_payments` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "stripe_payments", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePatch" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Invoice" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } }, "delete": { "tags": [ "Invoices" ], "summary": "Delete a draft invoice", "operationId": "invoicesDelete", "description": "Drafts only. An issued invoice stays on file: void it instead.\n\nScope: `write`. Needs the `stripe_payments` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "stripe_payments", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/invoices/{id}/issue": { "post": { "tags": [ "Invoices" ], "summary": "Issue an invoice", "operationId": "invoicesIssue", "description": "Numbers and freezes a draft (it needs at least one line). A total of 0 or less is issued straight to `paid`.\n\nScope: `write`. Needs the `stripe_payments` feature on the business's plan.\n\nEmits: `invoice.issued`, `invoice.paid`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "stripe_payments", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceIssueInput" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Invoice" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/invoices/{id}/line-items": { "get": { "tags": [ "Invoices" ], "summary": "List an invoice's line items", "operationId": "invoicesLinesList", "description": "Scope: `read`. Needs the `stripe_payments` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "x-feature": "stripe_payments", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLineItem" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "Invoices" ], "summary": "Add a line item", "operationId": "invoicesLinesCreate", "description": "Drafts only. Returns the whole invoice with its new totals.\n\nScope: `write`. Needs the `stripe_payments` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "stripe_payments", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceLineItemInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Invoice" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/invoices/{id}/line-items/{line_id}": { "patch": { "tags": [ "Invoices" ], "summary": "Update a line item", "operationId": "invoicesLinesUpdate", "description": "Drafts only. Returns the whole invoice with its new totals.\n\nScope: `write`. Needs the `stripe_payments` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "stripe_payments", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "line_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceLineItemPatch" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Invoice" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } }, "delete": { "tags": [ "Invoices" ], "summary": "Remove a line item", "operationId": "invoicesLinesDelete", "description": "Drafts only.\n\nScope: `write`. Needs the `stripe_payments` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "stripe_payments", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "line_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/invoices/{id}/pay-link": { "get": { "tags": [ "Invoices" ], "summary": "Get an invoice's pay link", "operationId": "invoicesPayLink", "description": "The public page where the client pays an open invoice. Reading it never changes it.\n\nScope: `read`. Needs the `stripe_payments` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "x-feature": "stripe_payments", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/InvoicePayLink" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/invoices/{id}/payments": { "get": { "tags": [ "Invoices" ], "summary": "List an invoice's payments", "operationId": "invoicesPaymentsList", "description": "Scope: `read`. Needs the `stripe_payments` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "x-feature": "stripe_payments", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoicePayment" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "Invoices" ], "summary": "Record a payment", "operationId": "invoicesPaymentsCreate", "description": "Money received outside the pay page, against an open invoice. When the balance reaches 0 the invoice is `paid`.\n\nScope: `write`. Needs the `stripe_payments` feature on the business's plan.\n\nEmits: `invoice.paid`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "stripe_payments", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePaymentInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Invoice" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/invoices/{id}/pdf": { "get": { "tags": [ "Invoices" ], "summary": "Download an invoice as PDF", "operationId": "invoicesPdf", "description": "The same document as the emailed copy, base64-encoded in JSON.\n\nScope: `read`. Needs the `stripe_payments` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "x-feature": "stripe_payments", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/InvoicePdf" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/invoices/{id}/send": { "post": { "tags": [ "Invoices" ], "summary": "Email an invoice again", "operationId": "invoicesSend", "description": "Open invoices only. The email carries a fresh pay link and earlier links stop working.\n\nScope: `write`. Needs the `stripe_payments` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "stripe_payments", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceSendInput" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/InvoiceSendResult" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/invoices/{id}/void": { "post": { "tags": [ "Invoices" ], "summary": "Void an invoice", "operationId": "invoicesVoid", "description": "Draft or open invoices with no money received. The pay link stops working.\n\nScope: `write`. Needs the `stripe_payments` feature on the business's plan.\n\nEmits: `invoice.voided`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "stripe_payments", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Invoice" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/me": { "get": { "tags": [ "Account" ], "summary": "Inspect the calling API key", "operationId": "metaMe", "description": "Which key you are using, its scope, and the business it acts for.\n\nScope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Me" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/meetings": { "get": { "tags": [ "Meetings & bookings" ], "summary": "List the calendar (meetings and bookings)", "operationId": "meetingsList", "description": "Meetings and bookings merged, by start time. Open a row with its `path`.\n\nScope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "kind", "in": "query", "required": false, "description": "`meeting` or `booking`; default both.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "YYYY-MM-DD; starting on or after this day.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "YYYY-MM-DD; starting on or before this day.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Exact status (the two kinds have different status sets).", "schema": { "type": "string" } }, { "name": "contact_id", "in": "query", "required": false, "description": "A contact of yours: meetings linked to it, and bookings made with its email.", "schema": { "type": "integer" } }, { "name": "product_id", "in": "query", "required": false, "description": "Bookings of this product (implies kind=booking).", "schema": { "type": "integer" } }, { "name": "updated_since", "in": "query", "required": false, "description": "ISO 8601; only rows changed at or after this time.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`starts_at` (default), `created_at` or `updated_at`; prefix `-` for descending.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CalendarItem" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Meetings & bookings" ], "summary": "Create a meeting", "operationId": "meetingsCreate", "description": "Adds it to the connected Google Calendar (and sheet) when the business has one.\n\nScope: `write`.\n\nEmits: `meeting.created`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetingInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Meeting" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/meetings/{id}": { "get": { "tags": [ "Meetings & bookings" ], "summary": "Retrieve a meeting", "operationId": "meetingsGet", "description": "Scope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Meeting" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Meetings & bookings" ], "summary": "Update a meeting", "operationId": "meetingsUpdate", "description": "Send only the fields you want to change. Change the status with PUT /meetings/{id}/status.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetingPatch" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Meeting" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/meetings/{id}/notes": { "get": { "tags": [ "Meetings & bookings" ], "summary": "Read a meeting's notes", "operationId": "meetingsNotesGet", "description": "Scope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/MeetingNotes" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "Meetings & bookings" ], "summary": "Add to a meeting's notes", "operationId": "meetingsNotesAdd", "description": "Scope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetingNoteInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/MeetingNotes" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/meetings/{id}/status": { "put": { "tags": [ "Meetings & bookings" ], "summary": "Set a meeting's status", "operationId": "meetingsStatus", "description": "Scope: `write`.\n\nEmits: `meeting.cancelled`, `meeting.completed`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetingStatusInput" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Meeting" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } }, "patch": { "tags": [ "Meetings & bookings" ], "summary": "Set a meeting's status (PATCH)", "operationId": "meetingsStatus", "description": "The same as PUT /meetings/{id}/status.\n\nScope: `write`.\n\nEmits: `meeting.cancelled`, `meeting.completed`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetingStatusInput" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Meeting" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/notifications": { "get": { "tags": [ "Notifications" ], "summary": "List notifications", "operationId": "notificationsList", "description": "Newest first.\n\nScope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "unread", "in": "query", "required": false, "description": "Only unread notifications.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Notification" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/notifications/read-all": { "post": { "tags": [ "Notifications" ], "summary": "Mark every notification read", "operationId": "notificationsReadAll", "description": "Scope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/NotificationsMarked" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/notifications/{id}/read": { "post": { "tags": [ "Notifications" ], "summary": "Mark a notification read", "operationId": "notificationsRead", "description": "Idempotent.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Notification" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/packages": { "get": { "tags": [ "Products" ], "summary": "List packages", "operationId": "packagesList", "description": "Scope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search name and description.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "`active` or `inactive`.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`display_order` (default), `name`, `created_at` or `updated_at`; prefix `-` for descending.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "ISO 8601; only packages changed at or after this time.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Package" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Products" ], "summary": "Create a package", "operationId": "packagesCreate", "description": "Scope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Package" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/packages/{id}": { "get": { "tags": [ "Products" ], "summary": "Retrieve a package", "operationId": "packagesGet", "description": "Scope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Package" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Products" ], "summary": "Update a package", "operationId": "packagesUpdate", "description": "Send only the fields you want to change; `items`, when sent, replaces them all.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackagePatch" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Package" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } }, "delete": { "tags": [ "Products" ], "summary": "Delete a package", "operationId": "packagesDelete", "description": "Packages are retired, not erased: it becomes `is_active: false`.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/ping": { "get": { "tags": [ "Account" ], "summary": "Check the API is reachable", "operationId": "metaPing", "description": "The cheapest authenticated call: confirms the key works and returns the server time.\n\nScope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Ping" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/planner/events": { "get": { "tags": [ "Planner" ], "summary": "List planner events", "operationId": "plannerEvents", "description": "Everything on the planner between two dates (inclusive, at most 62 days): scheduled tasks, meetings and Google events.\n\nScope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "YYYY-MM-DD; default today.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "YYYY-MM-DD; default `from`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PlannerEvents" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/planner/unscheduled": { "get": { "tags": [ "Planner" ], "summary": "List the backlog", "operationId": "plannerUnscheduled", "description": "Open tasks not on the calendar, most urgent first.\n\nScope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "project_id", "in": "query", "required": false, "description": "Only this project's tasks.", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "Search title and description.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/products": { "get": { "tags": [ "Products" ], "summary": "List products", "operationId": "productsList", "description": "Scope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search the name.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "`active` or `inactive`.", "schema": { "type": "string" } }, { "name": "category_id", "in": "query", "required": false, "description": "Only this category (0 = uncategorised).", "schema": { "type": "integer" } }, { "name": "updated_since", "in": "query", "required": false, "description": "ISO 8601; only products changed at or after this time.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`name`, `price`, `created_at` (default `-created_at`) or `updated_at`; prefix `-` for descending.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Products" ], "summary": "Create a product", "operationId": "productsCreate", "description": "Recurring pricing also creates the product and prices in the business's Stripe account when one is connected.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Product" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/products/{id}": { "get": { "tags": [ "Products" ], "summary": "Retrieve a product", "operationId": "productsGet", "description": "Scope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Product" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Products" ], "summary": "Update a product", "operationId": "productsUpdate", "description": "Send only the fields you want to change.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductPatch" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Product" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } }, "delete": { "tags": [ "Products" ], "summary": "Delete a product", "operationId": "productsDelete", "description": "A product that has bookings is deactivated (`is_active: false`) instead, so its history stays.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/products/{id}/schedules": { "get": { "tags": [ "Products" ], "summary": "List a product's schedules", "operationId": "productsSchedulesList", "description": "Scope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSchedule" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Products" ], "summary": "Replace a product's schedules", "operationId": "productsSchedulesReplace", "description": "Used when the product's `schedule_mode` is `custom_schedule`.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductSchedulesInput" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSchedule" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/projects": { "get": { "tags": [ "Projects" ], "summary": "List projects", "operationId": "projectsList", "description": "Newest first by default.\n\nScope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "`draft`, `active`, `on_hold`, `completed` or `cancelled`.", "schema": { "type": "string" } }, { "name": "client_id", "in": "query", "required": false, "description": "Only this contact's projects.", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "Search the project name.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "ISO 8601; only projects changed at or after this time.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`name`, `due_date`, `created_at` (default `-created_at`) or `updated_at`; prefix `-` for descending.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Projects" ], "summary": "Create a project", "operationId": "projectsCreate", "description": "`client_id` must be a contact of this business.\n\nScope: `write`.\n\nEmits: `project.created`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Project" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/projects/{id}": { "get": { "tags": [ "Projects" ], "summary": "Retrieve a project", "operationId": "projectsGet", "description": "One project with its task counts and progress.\n\nScope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Project" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Projects" ], "summary": "Update a project", "operationId": "projectsUpdate", "description": "Send only the fields you want to change. Moving to `completed` stamps `completed_at`.\n\nScope: `write`.\n\nEmits: `project.updated`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectPatch" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Project" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } }, "delete": { "tags": [ "Projects" ], "summary": "Delete a project", "operationId": "projectsDelete", "description": "Refused with `invalid_request` while the project still has tasks — delete them first.\n\nScope: `write`.\n\nEmits: `project.deleted`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/projects/{id}/clients": { "get": { "tags": [ "Projects" ], "summary": "List the client logins on a project", "operationId": "projectClientsList", "description": "Client users (role C) who can see this project when they sign in.\n\nScope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectClient" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "Projects" ], "summary": "Give a client login access", "operationId": "projectClientsAdd", "description": "`user_id` must be a client login of this business. Returns the project's updated client list.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectClientInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectClient" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/projects/{id}/clients/{user_id}": { "delete": { "tags": [ "Projects" ], "summary": "Remove a client login", "operationId": "projectClientsRemove", "description": "The user keeps their login; they just stop seeing this project.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/projects/{id}/deliverables": { "get": { "tags": [ "Projects" ], "summary": "List a project's deliverables", "operationId": "projectDeliverablesList", "description": "With their approval state and file metadata.\n\nScope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Deliverable" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "Projects" ], "summary": "Add a deliverable", "operationId": "projectDeliverablesCreate", "description": "`milestone_id`, when given, must be a milestone of this project.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliverableInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Deliverable" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/projects/{id}/deliverables/{deliverable_id}": { "patch": { "tags": [ "Projects" ], "summary": "Update a deliverable", "operationId": "projectDeliverablesUpdate", "description": "Send only the fields you want to change. Client approval happens in the portal (and emits `deliverable.approved`); setting `approved` here is a staff override and emits nothing.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "deliverable_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliverablePatch" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Deliverable" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } }, "delete": { "tags": [ "Projects" ], "summary": "Delete a deliverable", "operationId": "projectDeliverablesDelete", "description": "Its file records go with it.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "deliverable_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/projects/{id}/milestones": { "get": { "tags": [ "Projects" ], "summary": "List a project's milestones", "operationId": "projectMilestonesList", "description": "In timeline order.\n\nScope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Milestone" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "Projects" ], "summary": "Add a milestone", "operationId": "projectMilestonesCreate", "description": "Adds a step to the project timeline the client sees in the portal.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MilestoneInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Milestone" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/projects/{id}/milestones/{milestone_id}": { "patch": { "tags": [ "Projects" ], "summary": "Update a milestone", "operationId": "projectMilestonesUpdate", "description": "Send only the fields you want to change.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "milestone_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MilestonePatch" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Milestone" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } }, "delete": { "tags": [ "Projects" ], "summary": "Delete a milestone", "operationId": "projectMilestonesDelete", "description": "Deliverables linked to it keep existing.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "milestone_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/projects/{id}/portal": { "get": { "tags": [ "Projects" ], "summary": "Retrieve the client portal settings", "operationId": "projectPortalGet", "description": "Whether the project has a portal, whether it is enabled, and what it shows. The link itself is never returned here — only a hash is stored.\n\nScope: `read`. Needs the `client_portal` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "x-feature": "client_portal", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Portal" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "Projects" ], "summary": "Create or regenerate the portal link", "operationId": "projectPortalCreate", "description": "Creates the portal, or issues a **new** link (the old one stops working at once), and enables it. The response carries `url` — store it, it is shown only this once. Any settings sent are saved too.\n\nScope: `write`. Needs the `client_portal` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "client_portal", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortalInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Portal" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/projects/{id}/requests": { "get": { "tags": [ "Projects" ], "summary": "List requests to the client", "operationId": "projectRequestsList", "description": "Things you asked the client for (files, links, decisions), open first, with what they submitted.\n\nScope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ClientRequest" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "Projects" ], "summary": "Ask the client for something", "operationId": "projectRequestsCreate", "description": "Shows in the client portal until the client fulfils it.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientRequestInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ClientRequest" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/projects/{id}/requests/{request_id}": { "delete": { "tags": [ "Projects" ], "summary": "Delete a request", "operationId": "projectRequestsDelete", "description": "Its submissions go with it.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "request_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/projects/{id}/scope-items": { "get": { "tags": [ "Projects" ], "summary": "List a project's scope", "operationId": "projectScopeList", "description": "In-scope items first, then the explicitly excluded ones.\n\nScope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScopeItem" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "Projects" ], "summary": "Add a scope item", "operationId": "projectScopeCreate", "description": "Set `included: false` to record something as out of scope.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeItemInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ScopeItem" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/projects/{id}/scope-items/{scope_id}": { "patch": { "tags": [ "Projects" ], "summary": "Update a scope item", "operationId": "projectScopeUpdate", "description": "Send only the fields you want to change.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "scope_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeItemPatch" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ScopeItem" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } }, "delete": { "tags": [ "Projects" ], "summary": "Delete a scope item", "operationId": "projectScopeDelete", "description": "Removes the line from the project scope.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "scope_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/projects/{id}/updates": { "get": { "tags": [ "Projects" ], "summary": "List client updates", "operationId": "projectUpdatesList", "description": "Update emails drafted or sent for this project, newest first.\n\nScope: `read`. Needs the `client_updates` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "x-feature": "client_updates", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ClientUpdate" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "Projects" ], "summary": "Draft a client update", "operationId": "projectUpdatesCreate", "description": "Saves a **draft** — nothing is emailed until you send it. Write the subject and body yourself, or pass `generate: true` to have AI draft them from what changed since the last update.\n\nScope: `write`. Needs the `client_updates` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "client_updates", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientUpdateInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ClientUpdate" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/projects/{id}/updates/{update_id}/send": { "post": { "tags": [ "Projects" ], "summary": "Send a client update", "operationId": "projectUpdatesSend", "description": "Emails the draft to `to_email` from the business's verified sending domain. Refused if it has no recipient or was already sent.\n\nScope: `write`. Needs the `client_updates` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "client_updates", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "update_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ClientUpdate" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/proposals": { "get": { "tags": [ "Proposals" ], "summary": "List proposals", "operationId": "proposalsList", "description": "Sections, items and milestones are included when you retrieve one proposal.\n\nScope: `read`. Needs the `proposals` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "x-feature": "proposals", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "`draft`, `sent`, `opened`, `accepted`, `declined` or `expired`.", "schema": { "type": "string" } }, { "name": "client_id", "in": "query", "required": false, "description": "Only proposals for this contact.", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "Search title and number.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "ISO 8601; only proposals changed at or after this time.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`created_at` (default `-created_at`), `updated_at`, `title` or `total`; prefix `-` for descending.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProposalSummary" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Proposals" ], "summary": "Create a proposal", "operationId": "proposalsCreate", "description": "Creates a draft. Totals are calculated from the items, discount and tax.\n\nScope: `write`. Needs the `proposals` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "proposals", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Proposal" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/proposals/{id}": { "get": { "tags": [ "Proposals" ], "summary": "Retrieve a proposal", "operationId": "proposalsGet", "description": "Scope: `read`. Needs the `proposals` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "x-feature": "proposals", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Proposal" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Proposals" ], "summary": "Update a draft proposal", "operationId": "proposalsUpdate", "description": "Send only the fields you want to change. `sections`, `items` and `milestones`, when sent, replace the whole list.\n\nOnly a `draft` can be edited — once it is sent, the client is looking at it.\n\nScope: `write`. Needs the `proposals` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "proposals", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalPatch" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Proposal" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } }, "delete": { "tags": [ "Proposals" ], "summary": "Delete a proposal", "operationId": "proposalsDelete", "description": "An accepted proposal cannot be deleted (it is the record behind its project).\n\nScope: `write`. Needs the `proposals` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "proposals", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/proposals/{id}/convert": { "post": { "tags": [ "Proposals" ], "summary": "Create the project from an accepted proposal", "operationId": "proposalsConvert", "description": "Acceptance normally does this already. Idempotent: an accepted proposal only ever gets one project (`project_id`).\n\nScope: `write`. Needs the `proposals` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "proposals", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Proposal" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/proposals/{id}/deposit-invoice": { "post": { "tags": [ "Proposals" ], "summary": "Issue a deposit invoice", "operationId": "proposalsDeposit", "description": "For an accepted proposal: issues an invoice for part of the total and emails the client its pay link, as the panel does. Idempotent — one deposit invoice per proposal.\n\nScope: `write`. Needs the `proposals` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "proposals", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositInvoiceInput" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/DepositInvoice" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/proposals/{id}/pdf": { "get": { "tags": [ "Proposals" ], "summary": "Download a proposal as PDF", "operationId": "proposalsPdf", "description": "The same PDF the panel downloads, base64-encoded in `content_base64`.\n\nScope: `read`. Needs the `proposals` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "x-feature": "proposals", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ProposalPdf" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/proposals/{id}/regenerate-link": { "post": { "tags": [ "Proposals" ], "summary": "Issue a new client link", "operationId": "proposalsRegenerate", "description": "The old link stops working at once. Does not email anyone or change the status. Only for a proposal that has been sent.\n\nScope: `write`. Needs the `proposals` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "proposals", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ProposalSent" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/proposals/{id}/send": { "post": { "tags": [ "Proposals" ], "summary": "Send a proposal", "operationId": "proposalsSend", "description": "Numbers the proposal (first send), issues a fresh client link, marks it `sent` and, unless `send_email` is false, emails the client.\n\nThe response carries `public_url` — the only time it is shown. Sending again issues a new link and the old one stops working. Accepted or declined proposals cannot be re-sent.\n\nScope: `write`. Needs the `proposals` feature on the business's plan.\n\nEmits: `proposal.sent`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "proposals", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalSendInput" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ProposalSent" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/staff": { "get": { "tags": [ "Staff" ], "summary": "List staff", "operationId": "staffList", "description": "Scope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "role", "in": "query", "required": false, "description": "One of: owner, admin, member, client.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`name` (default) or `added_at`; prefix `-` for descending.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StaffMember" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/staff/{id}": { "post": { "tags": [ "Staff" ], "summary": "Add a user to the business", "operationId": "staffAdd", "description": "`{id}` is an existing user's id. Refused when they are already a member, or are the user who created this API key.\n\nScope: `admin`.", "security": [ { "ApiKey": [] } ], "x-scope": "admin", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/StaffMember" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "patch": { "tags": [ "Staff" ], "summary": "Change a staff member's role", "operationId": "staffUpdate", "description": "Scope: `admin`.", "security": [ { "ApiKey": [] } ], "x-scope": "admin", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffPatch" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/StaffMember" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } }, "delete": { "tags": [ "Staff" ], "summary": "Remove a user from the business", "operationId": "staffRemove", "description": "Their account stays; they lose access to this business. You cannot remove the user who created this API key.\n\nScope: `admin`.", "security": [ { "ApiKey": [] } ], "x-scope": "admin", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/submissions/{id}": { "get": { "tags": [ "Forms" ], "summary": "Retrieve a submission", "operationId": "submissionsGet", "description": "`form.submitted` webhooks carry this object.\n\nScope: `read`.\n\nEmits: `form.submitted`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/FormSubmission" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/subscribers": { "get": { "tags": [ "Newsletter" ], "summary": "List subscribers", "operationId": "subscribersList", "description": "Scope: `read`. Needs the `newsletter` feature on the business's plan.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "x-feature": "newsletter", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "`active` or `inactive` (default: both).", "schema": { "type": "string" } }, { "name": "email", "in": "query", "required": false, "description": "Exact email match (case-insensitive).", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "ISO 8601; only subscribers changed at or after this time.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`subscribed_at` (default `-subscribed_at`), `updated_at` or `email`; prefix `-` for descending.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Subscriber" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Newsletter" ], "summary": "Add a subscriber", "operationId": "subscribersCreate", "description": "Sends the welcome email, as the panel does. An inactive address is reactivated; an active one is refused. Needs the newsletter switched on in Settings → Newsletter.\n\nScope: `write`. Needs the `newsletter` feature on the business's plan.\n\nEmits: `subscriber.created`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "newsletter", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriberInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Subscriber" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/subscribers/{id}": { "delete": { "tags": [ "Newsletter" ], "summary": "Remove a subscriber", "operationId": "subscribersDelete", "description": "Marks the address inactive (the row is kept). Removing an inactive subscriber changes nothing.\n\nScope: `write`. Needs the `newsletter` feature on the business's plan.\n\nEmits: `subscriber.unsubscribed`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "x-feature": "newsletter", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/task-categories": { "get": { "tags": [ "Tasks" ], "summary": "List task categories", "operationId": "taskCategoriesList", "description": "Coloured categories (Design, Development…) used to filter the board.\n\nScope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "include_inactive", "in": "query", "required": false, "description": "Include archived categories.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TaskCategory" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Tasks" ], "summary": "Create a task category", "operationId": "taskCategoriesCreate", "description": "Names are unique within the business.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCategoryInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TaskCategory" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/task-categories/{id}": { "patch": { "tags": [ "Tasks" ], "summary": "Update a task category", "operationId": "taskCategoriesUpdate", "description": "Rename, recolour or archive (`is_active: false`).\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCategoryPatch" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TaskCategory" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } }, "delete": { "tags": [ "Tasks" ], "summary": "Delete a task category", "operationId": "taskCategoriesDelete", "description": "Its tasks keep everything else and become uncategorised.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/task-statuses": { "get": { "tags": [ "Tasks" ], "summary": "List task statuses", "operationId": "taskStatusesList", "description": "The board columns in order. A new business gets the default workflow (todo → done) on first read.\n\nScope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "include_inactive", "in": "query", "required": false, "description": "Include deactivated statuses.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TaskStatus" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Tasks" ], "summary": "Create a task status", "operationId": "taskStatusesCreate", "description": "Added as the last column. `key` must be unique in the business.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskStatusInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TaskStatus" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/task-statuses/{id}": { "patch": { "tags": [ "Tasks" ], "summary": "Update a task status", "operationId": "taskStatusesUpdate", "description": "Change the label, description or colour. The key never changes, so tasks stay put.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskStatusPatch" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TaskStatus" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } }, "delete": { "tags": [ "Tasks" ], "summary": "Delete a task status", "operationId": "taskStatusesDelete", "description": "Tasks in it move to `todo`. Built-in statuses cannot be deleted.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/tasks": { "get": { "tags": [ "Tasks" ], "summary": "List tasks", "operationId": "tasksList", "description": "Every task of the business, filtered as you like.\n\nScope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "project_id", "in": "query", "required": false, "description": "Only this project's tasks.", "schema": { "type": "integer" } }, { "name": "status", "in": "query", "required": false, "description": "Only tasks in this status key.", "schema": { "type": "string" } }, { "name": "is_done", "in": "query", "required": false, "description": "`true` for finished tasks, `false` for open ones.", "schema": { "type": "boolean" } }, { "name": "assigned_to", "in": "query", "required": false, "description": "A user id, or `none` for unassigned tasks.", "schema": { "type": "string" } }, { "name": "priority", "in": "query", "required": false, "description": "`low`, `medium`, `high` or `urgent`.", "schema": { "type": "string" } }, { "name": "category_id", "in": "query", "required": false, "description": "Only this category.", "schema": { "type": "integer" } }, { "name": "due_before", "in": "query", "required": false, "description": "YYYY-MM-DD; due on or before.", "schema": { "type": "string" } }, { "name": "due_after", "in": "query", "required": false, "description": "YYYY-MM-DD; due on or after.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "ISO 8601; only tasks changed at or after this time.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`title`, `due_date`, `created_at` (default `-created_at`) or `updated_at`; prefix `-` for descending.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Tasks" ], "summary": "Create a task", "operationId": "tasksCreate", "description": "`project_id`, `assigned_to`, `category_id` and `depends_on_task_id` must belong to this business. The assignee is notified.\n\nScope: `write`.\n\nEmits: `task.created`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Task" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/tasks/{id}": { "get": { "tags": [ "Tasks" ], "summary": "Retrieve a task", "operationId": "tasksGet", "description": "One task, with its schedule and done state.\n\nScope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Task" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Tasks" ], "summary": "Update a task", "operationId": "tasksUpdate", "description": "Send only the fields you want to change. Moving into a done status stamps `completed_at` and also emits `task.completed`; moving out clears it.\n\nScope: `write`.\n\nEmits: `task.updated`, `task.completed`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskPatch" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Task" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } }, "delete": { "tags": [ "Tasks" ], "summary": "Delete a task", "operationId": "tasksDelete", "description": "Refused with `invalid_request` while other tasks depend on it.\n\nScope: `write`.\n\nEmits: `task.deleted`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/tasks/{id}/schedule": { "post": { "tags": [ "Planner" ], "summary": "Schedule a task", "operationId": "plannerSchedule", "description": "Places the task on the planner (or moves it). Rescheduling an already-scheduled task replaces its slot.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskSchedule" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Task" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "delete": { "tags": [ "Planner" ], "summary": "Unschedule a task", "operationId": "plannerUnschedule", "description": "Takes the task off the calendar and back into the backlog. Returns the task.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Task" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/ticket-categories": { "get": { "tags": [ "Tickets" ], "summary": "List ticket categories", "operationId": "ticketCategoriesList", "description": "Scope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "active", "in": "query", "required": false, "description": "Only active categories (`true`) or only inactive ones (`false`).", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TicketCategory" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/tickets": { "get": { "tags": [ "Tickets" ], "summary": "List tickets", "operationId": "ticketsList", "description": "Scope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "One of: new, open, pending, resolved, closed.", "schema": { "type": "string" } }, { "name": "priority", "in": "query", "required": false, "description": "One of: low, medium, high, urgent.", "schema": { "type": "string" } }, { "name": "assignee_id", "in": "query", "required": false, "description": "Only tickets assigned to this staff user.", "schema": { "type": "integer" } }, { "name": "client_id", "in": "query", "required": false, "description": "Only tickets for this contact.", "schema": { "type": "integer" } }, { "name": "project_id", "in": "query", "required": false, "description": "Only tickets linked to this project.", "schema": { "type": "integer" } }, { "name": "category_id", "in": "query", "required": false, "description": "Only tickets in this category.", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "Search subject, number and description.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "ISO 8601; only tickets changed at or after this time.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`created_at` (default `-created_at`), `updated_at` or `last_reply_at`; prefix `-` for descending.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Ticket" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Tickets" ], "summary": "Open a ticket", "operationId": "ticketsCreate", "description": "Opened as `new`, numbered TK-YYYYMMDD-NNN. A category with a default assignee assigns it.\n\nScope: `write`.\n\nEmits: `ticket.created`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Ticket" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/tickets/{id}": { "get": { "tags": [ "Tickets" ], "summary": "Retrieve a ticket", "operationId": "ticketsGet", "description": "Scope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Ticket" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Tickets" ], "summary": "Update a ticket", "operationId": "ticketsUpdate", "description": "Send only the fields you want to change. Send `null` to clear the assignee, project, client or category.\n\nScope: `write`.\n\nEmits: `ticket.status_changed`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketPatch" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Ticket" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } }, "delete": { "tags": [ "Tickets" ], "summary": "Delete a ticket", "operationId": "ticketsDelete", "description": "Deletes its replies and attachments too.\n\nScope: `write`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/tickets/{id}/replies": { "get": { "tags": [ "Tickets" ], "summary": "List a ticket's replies", "operationId": "ticketsRepliesList", "description": "Oldest first.\n\nScope: `read`.", "security": [ { "ApiKey": [] } ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "include_internal", "in": "query", "required": false, "description": "Include internal notes (default true).", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TicketReply" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "Tickets" ], "summary": "Reply to a ticket", "operationId": "ticketsRepliesCreate", "description": "Adds an agent reply exactly as the ticket page does: on a ticket that came in over WhatsApp, a public reply is sent back to the client from your linked phone.\n\nScope: `write`.\n\nEmits: `ticket.replied`, `ticket.status_changed`.", "security": [ { "ApiKey": [] } ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketReplyInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketReply" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/webhook-endpoints": { "get": { "tags": [ "Developers" ], "summary": "List webhook endpoints", "operationId": "devEndpointsList", "description": "Scope: `admin`.", "security": [ { "ApiKey": [] } ], "x-scope": "admin", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Developers" ], "summary": "Create a webhook endpoint", "operationId": "devEndpointsCreate", "description": "Scope: `admin`.", "security": [ { "ApiKey": [] } ], "x-scope": "admin", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpointCreated" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/webhook-endpoints/{id}": { "get": { "tags": [ "Developers" ], "summary": "Retrieve a webhook endpoint", "operationId": "devEndpointsGet", "description": "Scope: `admin`.", "security": [ { "ApiKey": [] } ], "x-scope": "admin", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpoint" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Developers" ], "summary": "Update a webhook endpoint", "operationId": "devEndpointsUpdate", "description": "Scope: `admin`.", "security": [ { "ApiKey": [] } ], "x-scope": "admin", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointInput" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpoint" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } }, "delete": { "tags": [ "Developers" ], "summary": "Delete a webhook endpoint", "operationId": "devEndpointsDelete", "description": "Scope: `admin`.", "security": [ { "ApiKey": [] } ], "x-scope": "admin", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } } } }, "/webhook-endpoints/{id}/deliveries": { "get": { "tags": [ "Developers" ], "summary": "List recent deliveries", "operationId": "devDeliveriesList", "description": "Scope: `admin`.", "security": [ { "ApiKey": [] } ], "x-scope": "admin", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/webhook-endpoints/{id}/deliveries/{delivery_id}/retry": { "post": { "tags": [ "Developers" ], "summary": "Redeliver", "operationId": "devDeliveriesRetry", "description": "Puts a delivered or failed delivery back in the queue, due now.\n\nScope: `admin`.", "security": [ { "ApiKey": [] } ], "x-scope": "admin", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "delivery_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Accepted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": [ "object", "null" ] }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/webhook-endpoints/{id}/rotate-secret": { "post": { "tags": [ "Developers" ], "summary": "Rotate an endpoint's signing secret", "operationId": "devEndpointsRotate", "description": "The old secret stops verifying immediately.\n\nScope: `admin`.", "security": [ { "ApiKey": [] } ], "x-scope": "admin", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookSecret" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/webhook-endpoints/{id}/test": { "post": { "tags": [ "Developers" ], "summary": "Send a test event", "operationId": "devEndpointsTest", "description": "Queues a `webhook.test` delivery to this endpoint, whatever it subscribes to. It is sent on the next delivery run (within a minute or two).\n\nScope: `admin`.", "security": [ { "ApiKey": [] } ], "x-scope": "admin", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Accepted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": [ "object", "null" ] }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" } } } } }, "webhooks": { "contact.created": { "post": { "summary": "contact.created", "description": "A contact was added.\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.\n\nAlso emitted by: `POST /contacts`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "contact.updated": { "post": { "summary": "contact.updated", "description": "A contact's details changed.\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.\n\nAlso emitted by: `PATCH /contacts/{id}`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "contact.deleted": { "post": { "summary": "contact.deleted", "description": "A contact was deleted.\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.\n\nAlso emitted by: `DELETE /contacts/{id}`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "deal.status_changed": { "post": { "summary": "deal.status_changed", "description": "A contact moved to another pipeline status.\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.\n\nAlso emitted by: `PATCH /deals/{id}/status`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "deal.won": { "post": { "summary": "deal.won", "description": "A deal was marked won (the contact became a client).\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.\n\nAlso emitted by: `PATCH /deals/{id}/status`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "deal.lost": { "post": { "summary": "deal.lost", "description": "A deal was marked lost.\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "project.created": { "post": { "summary": "project.created", "description": "A project was created.\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.\n\nAlso emitted by: `POST /projects`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "project.updated": { "post": { "summary": "project.updated", "description": "A project's details or status changed.\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.\n\nAlso emitted by: `PATCH /projects/{id}`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "project.deleted": { "post": { "summary": "project.deleted", "description": "A project was deleted.\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.\n\nAlso emitted by: `DELETE /projects/{id}`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "task.created": { "post": { "summary": "task.created", "description": "A task was created.\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.\n\nAlso emitted by: `POST /tasks`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "task.updated": { "post": { "summary": "task.updated", "description": "A task changed.\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.\n\nAlso emitted by: `PATCH /tasks/{id}`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "task.completed": { "post": { "summary": "task.completed", "description": "A task moved to a terminal (done) status.\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.\n\nAlso emitted by: `PATCH /tasks/{id}`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "task.deleted": { "post": { "summary": "task.deleted", "description": "A task was deleted.\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.\n\nAlso emitted by: `DELETE /tasks/{id}`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "meeting.created": { "post": { "summary": "meeting.created", "description": "A meeting or booking was created.\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.\n\nAlso emitted by: `POST /meetings`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "meeting.cancelled": { "post": { "summary": "meeting.cancelled", "description": "A meeting or booking was cancelled.\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.\n\nAlso emitted by: `PUT /meetings/{id}/status`, `PATCH /meetings/{id}/status`, `PATCH /bookings/{id}/status`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "meeting.completed": { "post": { "summary": "meeting.completed", "description": "A meeting was marked completed.\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.\n\nAlso emitted by: `PUT /meetings/{id}/status`, `PATCH /meetings/{id}/status`, `PATCH /bookings/{id}/status`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "booking.created": { "post": { "summary": "booking.created", "description": "A customer booked through the public booking page.\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "booking.paid": { "post": { "summary": "booking.paid", "description": "A booking payment succeeded.\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.\n\nAlso emitted by: `POST /bookings/{id}/cash-payment`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "invoice.issued": { "post": { "summary": "invoice.issued", "description": "An invoice was issued (left draft).\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.\n\nAlso emitted by: `POST /bookings/{id}/cash-payment`, `POST /invoices/{id}/issue`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "invoice.paid": { "post": { "summary": "invoice.paid", "description": "An invoice was paid in full.\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.\n\nAlso emitted by: `POST /bookings/{id}/cash-payment`, `POST /invoices/{id}/issue`, `POST /invoices/{id}/payments`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "invoice.voided": { "post": { "summary": "invoice.voided", "description": "An invoice was voided.\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.\n\nAlso emitted by: `POST /invoices/{id}/void`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "proposal.sent": { "post": { "summary": "proposal.sent", "description": "A proposal was sent to the client.\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.\n\nAlso emitted by: `POST /proposals/{id}/send`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "proposal.accepted": { "post": { "summary": "proposal.accepted", "description": "The client accepted a proposal.\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "proposal.declined": { "post": { "summary": "proposal.declined", "description": "The client declined a proposal.\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "ticket.created": { "post": { "summary": "ticket.created", "description": "A support ticket was opened (panel, email, WhatsApp or the public form).\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.\n\nAlso emitted by: `POST /tickets`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "ticket.replied": { "post": { "summary": "ticket.replied", "description": "A reply was added to a ticket.\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.\n\nAlso emitted by: `POST /tickets/{id}/replies`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "ticket.status_changed": { "post": { "summary": "ticket.status_changed", "description": "A ticket's status changed.\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.\n\nAlso emitted by: `PATCH /tickets/{id}`, `POST /tickets/{id}/replies`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "form.submitted": { "post": { "summary": "form.submitted", "description": "An intake form was submitted.\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.\n\nAlso emitted by: `GET /submissions/{id}`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "subscriber.created": { "post": { "summary": "subscriber.created", "description": "Someone subscribed to the newsletter.\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.\n\nAlso emitted by: `POST /subscribers`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "subscriber.unsubscribed": { "post": { "summary": "subscriber.unsubscribed", "description": "Someone unsubscribed from the newsletter.\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.\n\nAlso emitted by: `DELETE /subscribers/{id}`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "deliverable.approved": { "post": { "summary": "deliverable.approved", "description": "A client approved a deliverable in the portal.\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "webhook.test": { "post": { "summary": "webhook.test", "description": "Sent by \"Send test\" — never emitted by real activity.\n\nSigned with `DA-Signature: t=,v1=` — see the Webhooks guide.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "dak1..", "description": "Create a key in **Settings → Developers**. Send it as `Authorization: Bearer `." } }, "parameters": { "Page": { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "PerPage": { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Make a POST safe to retry: the first response is replayed for 24 hours.", "schema": { "type": "string", "maxLength": 100 } } }, "responses": { "Unauthorized": { "description": "Missing, invalid or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "type": "unauthorized", "message": "Missing, invalid or revoked API key." }, "meta": { "request_id": "req_6f1c2a9e0b7d4c31" } } } } }, "Forbidden": { "description": "The key lacks the scope, or the plan lacks the feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "type": "forbidden", "message": "The key lacks the scope, or the plan lacks the feature." }, "meta": { "request_id": "req_6f1c2a9e0b7d4c31" } } } } }, "NotFound": { "description": "No such object in this business.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "type": "not_found", "message": "No such object in this business." }, "meta": { "request_id": "req_6f1c2a9e0b7d4c31" } } } } }, "Invalid": { "description": "The request body failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "type": "invalid_request", "message": "The request body failed validation." }, "meta": { "request_id": "req_6f1c2a9e0b7d4c31" } } } } }, "Conflict": { "description": "Idempotency-Key reused with a different request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "type": "conflict", "message": "Idempotency-Key reused with a different request." }, "meta": { "request_id": "req_6f1c2a9e0b7d4c31" } } } } }, "RateLimited": { "description": "Too many requests this minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "type": "rate_limited", "message": "Too many requests this minute." }, "meta": { "request_id": "req_6f1c2a9e0b7d4c31" } } } } } }, "schemas": { "Meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_6f1c2a9e0b7d4c31", "description": "Quote this when contacting support." } } }, "Pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "count": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" }, "has_more": { "type": "boolean" } } }, "ErrorEnvelope": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "type", "message" ], "properties": { "type": { "type": "string", "enum": [ "unauthorized", "forbidden", "feature_not_enabled", "not_found", "method_not_allowed", "conflict", "invalid_request", "rate_limited", "ai_unavailable", "server_error" ] }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "WebhookEvent": { "type": "object", "properties": { "id": { "type": "string", "example": "evt_84391785fc6136c8eb3b4529" }, "type": { "type": "string", "example": "invoice.paid" }, "created": { "type": "integer", "description": "Unix timestamp." }, "business_id": { "type": "integer" }, "data": { "type": "object", "description": "The object, in the same shape the API returns it.", "additionalProperties": true } } }, "Ping": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "time": { "type": "string", "format": "date-time" } } }, "Me": { "type": "object", "properties": { "key": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "scope": { "type": "string", "enum": [ "read", "write", "admin" ] } } }, "business": { "$ref": "#/components/schemas/Business" } } }, "Business": { "type": "object", "properties": { "id": { "type": "integer", "example": 12 }, "name": { "type": "string", "example": "Brightside Studio" }, "slug": { "type": [ "string", "null" ], "example": "brightside" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ], "example": "EUR" }, "timezone": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] }, "booking_page_url": { "type": [ "string", "null" ] } } }, "BusinessInput": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "website": { "type": "string" } } }, "Address": { "type": "object", "properties": { "line1": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] } } }, "Contact": { "type": "object", "properties": { "id": { "type": "integer", "example": 101 }, "name": { "type": "string", "example": "Aoife Byrne" }, "company": { "type": [ "string", "null" ], "example": "Byrne Bakeries" }, "email": { "type": [ "string", "null" ], "format": "email", "example": "aoife@example.com" }, "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "client", "prospect" ], "example": "prospect" }, "crm_status": { "type": [ "string", "null" ], "example": "lead", "description": "Pipeline status key (see GET /deal-statuses)." }, "estimated_value": { "type": [ "number", "null" ], "example": 4500 }, "expected_close_date": { "type": [ "string", "null" ], "format": "date" }, "address": { "$ref": "#/components/schemas/Address" }, "billing_address": { "$ref": "#/components/schemas/Address" }, "billing_email": { "type": [ "string", "null" ] }, "vat_number": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ContactInput": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "company": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "website": { "type": "string" }, "type": { "type": "string", "enum": [ "client", "prospect" ] }, "crm_status": { "type": "string", "description": "Create only; use PATCH /deals/{id}/status to move a contact afterwards." }, "estimated_value": { "type": "number" }, "expected_close_date": { "type": "string", "format": "date" }, "address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "postal_code": { "type": "string" }, "billing_address": { "type": "string" }, "billing_city": { "type": "string" }, "billing_state": { "type": "string" }, "billing_country": { "type": "string" }, "billing_postal_code": { "type": "string" }, "notes": { "type": "string" } }, "required": [ "name" ] }, "ContactPatch": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "company": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "website": { "type": "string" }, "type": { "type": "string", "enum": [ "client", "prospect" ] }, "estimated_value": { "type": "number" }, "expected_close_date": { "type": "string", "format": "date" }, "address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "postal_code": { "type": "string" }, "billing_address": { "type": "string" }, "billing_city": { "type": "string" }, "billing_state": { "type": "string" }, "billing_country": { "type": "string" }, "billing_postal_code": { "type": "string" }, "notes": { "type": "string" } } }, "ContactNote": { "type": "object", "properties": { "id": { "type": "integer" }, "contact_id": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "method": { "type": "string", "enum": [ "call", "email", "whatsapp", "inperson", "internal" ] }, "note": { "type": "string" }, "user_id": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "ContactNoteInput": { "type": "object", "required": [ "note" ], "properties": { "note": { "type": "string" }, "date": { "type": "string", "format": "date", "description": "Defaults to today." }, "method": { "type": "string", "enum": [ "call", "email", "whatsapp", "inperson", "internal" ], "default": "internal" } } }, "Deal": { "type": "object", "properties": { "id": { "type": "integer", "example": 101, "description": "The contact id — a deal is a contact." }, "name": { "type": "string", "example": "Aoife Byrne" }, "company": { "type": [ "string", "null" ], "example": "Byrne Bakeries" }, "email": { "type": [ "string", "null" ], "format": "email", "example": "aoife@example.com" }, "phone": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "client", "prospect" ], "example": "prospect" }, "status": { "type": "string", "example": "proposal", "description": "Pipeline status key (see GET /deal-statuses). A contact with none is a `lead`." }, "value": { "type": [ "number", "null" ], "example": 4500, "description": "Estimated deal value, in the business currency." }, "expected_close_date": { "type": [ "string", "null" ], "format": "date", "example": "2026-12-15" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "DealStatusChange": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "example": "closed_won", "description": "Key of an active pipeline status of this business." } } }, "DealStatus": { "type": "object", "properties": { "id": { "type": "integer", "example": 41 }, "key": { "type": "string", "example": "proposal", "description": "Stable key stored on the deal." }, "label": { "type": "string", "example": "Proposal" }, "description": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ], "example": "#ffc107" }, "sort_order": { "type": "integer", "example": 3 }, "is_active": { "type": "boolean" }, "is_default": { "type": "boolean", "description": "Built-in statuses can be relabelled but not deleted." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "DealStatusInput": { "type": "object", "required": [ "key", "label" ], "properties": { "key": { "type": "string", "pattern": "^[a-z0-9_]{1,50}$", "example": "discovery_call" }, "label": { "type": "string", "maxLength": 100, "example": "Discovery call" }, "description": { "type": "string" }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "example": "#17a2b8" } } }, "DealStatusPatch": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 100 }, "description": { "type": "string" }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" } } }, "DealForecast": { "type": "object", "properties": { "by_status": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "example": "proposal" }, "label": { "type": "string", "example": "Proposal" }, "count": { "type": "integer", "example": 4 }, "value": { "type": "number", "example": 18000 } } }, "description": "Every pipeline status in order, with the count and summed estimated value of its deals." }, "by_close_month": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": [ "string", "null" ], "example": "2026-12", "description": "`YYYY-MM`; null for open deals with no expected close date." }, "count": { "type": "integer", "example": 4 }, "value": { "type": "number", "example": 18000 } } }, "description": "Open deals (not won or lost) by expected close month." }, "revenue": { "type": "object", "description": "The panel's service-based revenue forecast (active client services).", "properties": { "periods": { "type": "object", "additionalProperties": { "type": "object", "properties": { "label": { "type": "string", "example": "Next 3 Months" }, "revenue": { "type": "number" }, "service_count": { "type": "integer" }, "client_count": { "type": "integer" } } }, "description": "Keyed `current_month`, `next_month`, `next_3_months`, `next_12_months` (+ `custom` with from/to)." }, "monthly": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string", "example": "2026-12" }, "revenue": { "type": "number" } } } } } } } }, "Project": { "type": "object", "properties": { "id": { "type": "integer", "example": 55 }, "name": { "type": "string", "example": "Website redesign" }, "description": { "type": [ "string", "null" ] }, "client_id": { "type": "integer", "example": 101 }, "client_name": { "type": [ "string", "null" ], "example": "Aoife Byrne" }, "status": { "type": "string", "enum": [ "draft", "active", "on_hold", "completed", "cancelled" ], "example": "active" }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ], "example": "medium" }, "budget": { "type": [ "number", "null" ], "example": 12000 }, "hourly_rate": { "type": [ "number", "null" ] }, "estimated_hours": { "type": [ "integer", "null" ] }, "actual_hours": { "type": [ "number", "null" ] }, "start_date": { "type": [ "string", "null" ], "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "progress_percent": { "type": "integer", "example": 40, "description": "Share of the project's tasks in a done status." }, "total_tasks": { "type": "integer" }, "completed_tasks": { "type": "integer" }, "total_billed": { "type": [ "number", "null" ] }, "project_manager_id": { "type": [ "integer", "null" ] }, "notes": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ProjectInput": { "type": "object", "required": [ "name", "client_id" ], "properties": { "name": { "type": "string", "maxLength": 255, "example": "Website redesign" }, "client_id": { "type": "integer", "example": 101, "description": "A contact of this business." }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "on_hold", "completed", "cancelled" ], "default": "draft" }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ], "default": "medium" }, "budget": { "type": "number", "example": 12000 }, "hourly_rate": { "type": "number", "example": 95 }, "estimated_hours": { "type": "integer", "example": 120 }, "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "project_manager_id": { "type": "integer", "description": "A user of this business (see GET /staff)." }, "notes": { "type": "string" } } }, "ProjectPatch": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "example": "Website redesign" }, "client_id": { "type": "integer", "example": 101, "description": "A contact of this business." }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "on_hold", "completed", "cancelled" ], "default": "draft" }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ], "default": "medium" }, "budget": { "type": "number", "example": 12000 }, "hourly_rate": { "type": "number", "example": 95 }, "estimated_hours": { "type": "integer", "example": 120 }, "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "project_manager_id": { "type": "integer", "description": "A user of this business (see GET /staff)." }, "notes": { "type": "string" } } }, "Milestone": { "type": "object", "properties": { "id": { "type": "integer", "example": 7 }, "project_id": { "type": "integer" }, "title": { "type": "string", "example": "Design sign-off" }, "description": { "type": [ "string", "null" ] }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "status": { "type": "string", "enum": [ "upcoming", "in_progress", "complete" ], "example": "upcoming" }, "sort_order": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "MilestoneInput": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "maxLength": 255 }, "description": { "type": "string" }, "due_date": { "type": "string", "format": "date" }, "status": { "type": "string", "enum": [ "upcoming", "in_progress", "complete" ], "default": "upcoming" }, "sort_order": { "type": "integer" } } }, "MilestonePatch": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "status": { "type": "string", "enum": [ "upcoming", "in_progress", "complete" ] } } }, "Deliverable": { "type": "object", "properties": { "id": { "type": "integer", "example": 12 }, "project_id": { "type": "integer" }, "milestone_id": { "type": [ "integer", "null" ] }, "title": { "type": "string", "example": "Homepage mock-up" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "in_progress", "ready_for_review", "approved", "delivered" ], "example": "ready_for_review" }, "sort_order": { "type": "integer" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "approved_by_name": { "type": [ "string", "null" ] }, "approved_by_email": { "type": [ "string", "null" ] }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "size": { "type": "integer" }, "mime": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "description": "File metadata only; download files from the panel or the portal." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "DeliverableInput": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "maxLength": 255 }, "description": { "type": "string" }, "milestone_id": { "type": "integer", "description": "A milestone of the same project." }, "status": { "type": "string", "enum": [ "in_progress", "ready_for_review", "approved", "delivered" ], "default": "in_progress" }, "sort_order": { "type": "integer" } } }, "DeliverablePatch": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "milestone_id": { "type": [ "integer", "null" ] }, "status": { "type": "string", "enum": [ "in_progress", "ready_for_review", "approved", "delivered" ], "description": "Staff-side status. `ready_for_review` shows it to the client for approval." } } }, "ScopeItem": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "title": { "type": "string", "example": "Up to 8 page templates" }, "included": { "type": "boolean", "description": "false = explicitly out of scope." }, "sort_order": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ScopeItemInput": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "maxLength": 500 }, "included": { "type": "boolean", "default": true }, "sort_order": { "type": "integer" } } }, "ScopeItemPatch": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 500 }, "included": { "type": "boolean" } } }, "ClientRequest": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "type": { "type": "string", "enum": [ "file", "link", "approval", "decision", "text" ], "example": "file" }, "title": { "type": "string", "example": "Send us your logo files" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "open", "fulfilled" ] }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "fulfilled_at": { "type": [ "string", "null" ], "format": "date-time" }, "submissions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "file_name": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "submitted_at": { "type": "string", "format": "date-time" } } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ClientRequestInput": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "maxLength": 255 }, "type": { "type": "string", "enum": [ "file", "link", "approval", "decision", "text" ], "default": "text" }, "description": { "type": "string" }, "due_date": { "type": "string", "format": "date" } } }, "ProjectClient": { "type": "object", "properties": { "user_id": { "type": "integer", "example": 321 }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "access_level": { "type": "string", "example": "read_only" }, "assigned_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ProjectClientInput": { "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": "integer", "description": "A client login (role C) of this business." } } }, "ClientUpdate": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "type": { "type": "string", "enum": [ "status", "milestone", "review_nudge", "waiting_on_you", "kickoff", "custom" ] }, "to_email": { "type": [ "string", "null" ] }, "subject": { "type": [ "string", "null" ], "example": "Your website: this week" }, "body_html": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "sent" ] }, "sent_via": { "type": [ "string", "null" ], "enum": [ "email", "copied" ] }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ClientUpdateInput": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "status", "milestone", "review_nudge", "waiting_on_you", "kickoff", "custom" ], "default": "status" }, "subject": { "type": "string", "maxLength": 255, "description": "Required unless `generate` is true." }, "body_html": { "type": "string", "description": "Required unless `generate` is true." }, "to_email": { "type": "string", "format": "email", "description": "Defaults to the project client's email." }, "generate": { "type": "boolean", "default": false, "description": "Draft subject and body with AI from what changed on the project. 422 when AI is not configured." }, "custom_instruction": { "type": "string", "description": "Extra guidance for the AI draft." } } }, "Portal": { "type": "object", "properties": { "exists": { "type": "boolean", "description": "false until a portal link was created." }, "enabled": { "type": "boolean" }, "url": { "type": [ "string", "null" ], "example": "https://app.digitalagency.tools/portal/3f…", "description": "Only in the POST response, once. Never retrievable afterwards." }, "welcome_message": { "type": [ "string", "null" ], "example": "Hi Aoife — everything for the redesign lives here." }, "show_ai_summary": { "type": "boolean" }, "show_booking": { "type": "boolean" }, "show_tickets": { "type": "boolean" }, "show_invoices": { "type": "boolean" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_viewed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "PortalInput": { "type": "object", "properties": { "welcome_message": { "type": [ "string", "null" ], "example": "Hi Aoife — everything for the redesign lives here." }, "show_ai_summary": { "type": "boolean" }, "show_booking": { "type": "boolean" }, "show_tickets": { "type": "boolean" }, "show_invoices": { "type": "boolean" } } }, "Task": { "type": "object", "properties": { "id": { "type": "integer", "example": 901 }, "project_id": { "type": "integer", "example": 55 }, "project_name": { "type": [ "string", "null" ], "example": "Website redesign" }, "milestone_id": { "type": [ "integer", "null" ] }, "title": { "type": "string", "example": "Build the pricing page" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "example": "in_progress" }, "is_done": { "type": "boolean", "example": false }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ], "example": "high" }, "assigned_to": { "type": [ "integer", "null" ], "example": 3 }, "assigned_to_name": { "type": [ "string", "null" ] }, "category_id": { "type": [ "integer", "null" ] }, "category_name": { "type": [ "string", "null" ], "example": "Development" }, "due_date": { "type": [ "string", "null" ], "format": "date", "example": "2026-11-20" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "estimated_hours": { "type": [ "number", "null" ] }, "actual_hours": { "type": [ "number", "null" ] }, "billable_hours": { "type": [ "number", "null" ] }, "hourly_rate": { "type": [ "number", "null" ] }, "total_billed": { "type": [ "number", "null" ] }, "depends_on_task_id": { "type": [ "integer", "null" ] }, "tags": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "schedule": { "type": [ "object", "null" ], "description": "Where the task sits on the planner; null when unscheduled.", "properties": { "date": { "type": "string", "format": "date", "example": "2026-11-12" }, "start_time": { "type": "string", "example": "09:30" }, "duration_minutes": { "type": "integer", "example": 90 } } }, "sort_order": { "type": "integer" }, "created_by": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "TaskInput": { "type": "object", "required": [ "title", "project_id" ], "properties": { "title": { "type": "string", "maxLength": 255, "example": "Build the pricing page" }, "project_id": { "type": "integer", "example": 55, "description": "A project of this business." }, "description": { "type": "string" }, "status": { "type": "string", "example": "in_progress", "description": "A status key of this business (GET /task-statuses). Default `todo`." }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ], "default": "medium" }, "assigned_to": { "type": [ "integer", "null" ], "description": "A user of this business." }, "category_id": { "type": [ "integer", "null" ], "description": "A task category of this business." }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "estimated_hours": { "type": "number" }, "billable_hours": { "type": "number" }, "hourly_rate": { "type": "number" }, "depends_on_task_id": { "type": [ "integer", "null" ], "description": "Another task of this business." }, "tags": { "type": [ "string", "null" ], "example": "homepage, copy" }, "notes": { "type": [ "string", "null" ] } } }, "TaskPatch": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255, "example": "Build the pricing page" }, "project_id": { "type": "integer", "example": 55, "description": "A project of this business." }, "description": { "type": "string" }, "status": { "type": "string", "example": "in_progress", "description": "A status key of this business (GET /task-statuses). Default `todo`." }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ], "default": "medium" }, "assigned_to": { "type": [ "integer", "null" ], "description": "A user of this business." }, "category_id": { "type": [ "integer", "null" ], "description": "A task category of this business." }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "estimated_hours": { "type": "number" }, "actual_hours": { "type": "number", "description": "Update only." }, "billable_hours": { "type": "number" }, "hourly_rate": { "type": "number" }, "depends_on_task_id": { "type": [ "integer", "null" ], "description": "Another task of this business." }, "tags": { "type": [ "string", "null" ], "example": "homepage, copy" }, "notes": { "type": [ "string", "null" ] } } }, "TaskStatus": { "type": "object", "properties": { "id": { "type": "integer", "example": 14 }, "key": { "type": "string", "example": "in_progress" }, "label": { "type": "string", "example": "IN PROGRESS" }, "description": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ], "example": "#f59e0b" }, "sort_order": { "type": "integer" }, "is_active": { "type": "boolean" }, "is_default": { "type": "boolean", "description": "Built-in statuses can be relabelled but not deleted." }, "is_terminal": { "type": "boolean", "description": "Tasks in this status count as done." } } }, "TaskStatusInput": { "type": "object", "required": [ "key", "label" ], "properties": { "key": { "type": "string", "pattern": "^[a-z0-9_]{1,50}$", "example": "in_review" }, "label": { "type": "string", "maxLength": 100, "example": "In review" }, "description": { "type": "string" }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "example": "#f59e0b" } } }, "TaskStatusPatch": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 100, "example": "In review" }, "description": { "type": "string" }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "example": "#f59e0b" } } }, "TaskCategory": { "type": "object", "properties": { "id": { "type": "integer", "example": 3 }, "name": { "type": "string", "example": "Development" }, "color": { "type": "string", "example": "#2f80ed" }, "sort_order": { "type": "integer" }, "is_active": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "TaskCategoryInput": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 80 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" } } }, "TaskCategoryPatch": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 80 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "is_active": { "type": "boolean" } } }, "PlannerMeeting": { "type": "object", "properties": { "id": { "type": "integer", "example": 77 }, "title": { "type": "string", "example": "Kick-off call" }, "start": { "type": "string", "format": "date-time" }, "duration_minutes": { "type": "integer", "example": 60 }, "status": { "type": "string", "example": "confirmed" }, "client_id": { "type": [ "integer", "null" ] } } }, "PlannerGoogleEvent": { "type": "object", "properties": { "id": { "type": "string" }, "calendar_id": { "type": "string" }, "summary": { "type": [ "string", "null" ] }, "start": { "type": "string", "description": "RFC 3339 date-time, or a date for all-day events." }, "end": { "type": "string" }, "location": { "type": [ "string", "null" ] } } }, "PlannerEvents": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/Task" }, "description": "Scheduled, open tasks in the range." }, "meetings": { "type": "array", "items": { "$ref": "#/components/schemas/PlannerMeeting" } }, "google": { "type": "array", "items": { "$ref": "#/components/schemas/PlannerGoogleEvent" }, "description": "Only the calendars enabled in the planner settings." }, "stats": { "type": "object", "properties": { "total_scheduled_minutes": { "type": "integer" }, "available_minutes": { "type": "integer" }, "work_day_minutes": { "type": "integer" }, "events_count": { "type": "integer" }, "workload_percentage": { "type": "integer" } }, "description": "Workload against one working day (the planner's work hours)." } } }, "TaskSchedule": { "type": "object", "required": [ "date" ], "properties": { "date": { "type": "string", "format": "date", "example": "2026-11-12" }, "start_time": { "type": "string", "example": "09:30", "default": "09:00", "description": "HH:MM (24-hour)." }, "duration_minutes": { "type": "integer", "minimum": 5, "maximum": 1440, "default": 60 } } }, "MeetingCustomer": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] } } }, "CalendarItem": { "type": "object", "description": "A meeting or a booking in the merged calendar.", "properties": { "kind": { "type": "string", "enum": [ "meeting", "booking" ] }, "id": { "type": "integer", "description": "The meeting id or the booking id, depending on `kind`." }, "path": { "type": "string", "example": "/meetings/12", "description": "The resource for this row." }, "title": { "type": "string" }, "starts_at": { "type": [ "string", "null" ], "format": "date-time" }, "ends_at": { "type": [ "string", "null" ], "format": "date-time" }, "duration_minutes": { "type": [ "integer", "null" ] }, "status": { "type": "string", "description": "Meeting statuses: draft, scheduled, confirmed, in_progress, completed, cancelled, no_show. Booking statuses: pending, confirmed, completed, cancelled, no_show." }, "payment_status": { "type": [ "string", "null" ] }, "customer": { "$ref": "#/components/schemas/MeetingCustomer" }, "contact_id": { "type": [ "integer", "null" ], "description": "Meetings only (bookings are matched to contacts by email)." }, "product_id": { "type": [ "integer", "null" ], "description": "Bookings only." }, "total_amount": { "type": [ "number", "null" ], "example": 120, "description": "Decimal, in `currency`." }, "currency": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Meeting": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "meeting" ] }, "id": { "type": "integer", "example": 12 }, "title": { "type": "string", "example": "Kick-off call" }, "description": { "type": [ "string", "null" ] }, "meeting_type": { "type": "string", "enum": [ "consultation", "presentation", "workshop", "call", "training", "other" ] }, "starts_at": { "type": [ "string", "null" ], "format": "date-time" }, "ends_at": { "type": [ "string", "null" ], "format": "date-time" }, "duration_minutes": { "type": "integer" }, "timezone": { "type": [ "string", "null" ] }, "location_type": { "type": [ "string", "null" ], "enum": [ "in_person", "online", "phone", "hybrid" ] }, "location": { "type": [ "string", "null" ] }, "meeting_url": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "scheduled", "confirmed", "in_progress", "completed", "cancelled", "no_show" ] }, "payment_status": { "type": [ "string", "null" ] }, "contact_id": { "type": [ "integer", "null" ] }, "customer": { "$ref": "#/components/schemas/MeetingCustomer" }, "total_amount": { "type": [ "number", "null" ], "example": 120, "description": "Decimal, in `currency`." }, "currency": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "MeetingInput": { "type": "object", "required": [ "starts_at" ], "properties": { "title": { "type": "string", "maxLength": 255, "description": "Defaults to \"Meeting with \"." }, "description": { "type": "string" }, "meeting_type": { "type": "string", "enum": [ "consultation", "presentation", "workshop", "call", "training", "other" ], "default": "consultation" }, "starts_at": { "type": "string", "format": "date-time", "example": "2026-11-20T10:00:00+00:00" }, "duration_minutes": { "type": "integer", "minimum": 1, "maximum": 1440, "default": 60 }, "timezone": { "type": "string", "example": "Europe/Dublin", "default": "UTC" }, "location_type": { "type": "string", "enum": [ "in_person", "online", "phone", "hybrid" ], "default": "online" }, "location": { "type": "string" }, "meeting_url": { "type": "string", "format": "uri" }, "contact_id": { "type": "integer", "description": "A contact of this business. Customer fields you leave out are copied from it." }, "customer_name": { "type": "string", "description": "Required unless `contact_id` is sent." }, "customer_email": { "type": "string", "format": "email" }, "customer_phone": { "type": "string" }, "customer_company": { "type": "string" }, "internal_notes": { "type": "string", "description": "Private to the business." }, "status": { "type": "string", "enum": [ "draft", "scheduled", "confirmed" ], "default": "scheduled" } } }, "MeetingPatch": { "type": "object", "description": "Send only what changes. The status moves through PUT /meetings/{id}/status.", "properties": { "title": { "type": "string", "maxLength": 255, "description": "Defaults to \"Meeting with \"." }, "description": { "type": "string" }, "meeting_type": { "type": "string", "enum": [ "consultation", "presentation", "workshop", "call", "training", "other" ], "default": "consultation" }, "starts_at": { "type": "string", "format": "date-time", "example": "2026-11-20T10:00:00+00:00" }, "duration_minutes": { "type": "integer", "minimum": 1, "maximum": 1440, "default": 60 }, "timezone": { "type": "string", "example": "Europe/Dublin", "default": "UTC" }, "location_type": { "type": "string", "enum": [ "in_person", "online", "phone", "hybrid" ], "default": "online" }, "location": { "type": "string" }, "meeting_url": { "type": "string", "format": "uri" }, "contact_id": { "type": "integer", "description": "A contact of this business. Customer fields you leave out are copied from it." }, "customer_name": { "type": "string", "description": "Required unless `contact_id` is sent." }, "customer_email": { "type": "string", "format": "email" }, "customer_phone": { "type": "string" }, "customer_company": { "type": "string" }, "internal_notes": { "type": "string", "description": "Private to the business." } } }, "MeetingStatusInput": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "draft", "scheduled", "confirmed", "in_progress", "completed", "cancelled", "no_show" ] }, "note": { "type": "string", "description": "Optional; appended to the internal notes with the time." } } }, "MeetingNotes": { "type": "object", "properties": { "meeting_id": { "type": "integer" }, "notes": { "type": "string", "description": "The meeting's internal notes: one text, newest entries last, each dated." } } }, "MeetingNoteInput": { "type": "object", "required": [ "note" ], "properties": { "note": { "type": "string", "description": "Appended as \"YYYY-MM-DD HH:MM:SS - \"." } } }, "Booking": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "booking" ] }, "id": { "type": "integer", "example": 340 }, "product_id": { "type": [ "integer", "null" ] }, "product_name": { "type": [ "string", "null" ] }, "starts_at": { "type": [ "string", "null" ], "format": "date-time" }, "ends_at": { "type": [ "string", "null" ], "format": "date-time" }, "duration_minutes": { "type": [ "integer", "null" ] }, "status": { "type": "string", "enum": [ "pending", "confirmed", "completed", "cancelled", "no_show" ] }, "payment_status": { "type": [ "string", "null" ], "example": "paid" }, "participants_count": { "type": "integer" }, "customer": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "vat_number": { "type": [ "string", "null" ] } } }, "customer_notes": { "type": [ "string", "null" ], "description": "What the customer wrote when booking." }, "subtotal": { "type": [ "number", "null" ], "example": 120, "description": "Decimal, in `currency`." }, "vat_rate": { "type": [ "number", "null" ], "description": "Percent." }, "vat_amount": { "type": [ "number", "null" ], "example": 120, "description": "Decimal, in `currency`." }, "coupon_code": { "type": [ "string", "null" ] }, "coupon_discount": { "type": [ "number", "null" ], "example": 120, "description": "Decimal, in `currency`." }, "total_amount": { "type": [ "number", "null" ], "example": 120, "description": "Decimal, in `currency`." }, "currency": { "type": [ "string", "null" ] }, "refund": { "type": [ "object", "null" ], "properties": { "amount": { "type": "number" }, "status": { "type": "string", "enum": [ "partial", "refunded" ] }, "processed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "zoom_join_url": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "BookingStatusInput": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "pending", "confirmed", "completed", "cancelled", "no_show" ] } } }, "BookingPaymentLink": { "type": "object", "properties": { "payment_url": { "type": "string", "format": "uri" }, "amount": { "type": "number" }, "currency": { "type": "string" } } }, "BookingReminderResult": { "type": "object", "properties": { "sent": { "type": "boolean" }, "amount_remaining": { "type": "number" } } }, "BookingCashPaymentInput": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "number", "description": "VAT-inclusive, no more than the outstanding balance.", "example": 50 }, "notes": { "type": "string", "description": "Added to the booking's internal notes." } } }, "BookingCashPaymentResult": { "type": "object", "properties": { "invoice_id": { "type": "integer", "description": "The paid receipt raised for it (GET /invoices/{id})." }, "invoice_number": { "type": "string" }, "booking": { "$ref": "#/components/schemas/Booking" } } }, "BookingRefundInput": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "number", "description": "More than 0 and no more than the booking total." }, "reason": { "type": "string", "enum": [ "requested_by_customer", "duplicate", "fraudulent" ], "default": "requested_by_customer" }, "notes": { "type": "string" } } }, "BookingRefundResult": { "type": "object", "properties": { "refund_id": { "type": "string", "description": "The card processor's refund id." }, "amount": { "type": "number" }, "booking": { "$ref": "#/components/schemas/Booking" } } }, "Availability": { "type": "object", "properties": { "product_id": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "timezone": { "type": [ "string", "null" ] }, "slots": { "type": "array", "items": { "type": "object", "properties": { "starts_at": { "type": "string", "example": "2026-11-20 10:00:00", "description": "Business-local date and time." }, "time": { "type": "string", "example": "10:00:00" }, "display": { "type": [ "string", "null" ], "example": "10:00 AM" }, "available": { "type": "boolean" }, "reason": { "type": [ "string", "null" ], "example": "Already booked" }, "capacity": { "type": [ "object", "null" ], "description": "Group products only.", "properties": { "current": { "type": "integer" }, "max": { "type": "integer" }, "available": { "type": "integer" } } } } } } } }, "Product": { "type": "object", "properties": { "id": { "type": "integer", "example": 21 }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "category_id": { "type": [ "integer", "null" ] }, "price": { "type": "number" }, "currency": { "type": [ "string", "null" ] }, "pricing_type": { "type": "string", "enum": [ "once_off", "recurring", "both" ] }, "recurring_price": { "type": [ "number", "null" ] }, "recurring_interval": { "type": [ "string", "null" ] }, "duration_minutes": { "type": [ "integer", "null" ], "description": "Read-only here." }, "buffer_minutes": { "type": [ "integer", "null" ], "description": "Read-only here." }, "max_participants": { "type": [ "integer", "null" ], "description": "Read-only here." }, "booking_type": { "type": [ "string", "null" ], "example": "individual", "description": "`individual` or `group`. Read-only here." }, "schedule_mode": { "type": [ "string", "null" ], "example": "business_hours", "description": "`business_hours` or `custom_schedule`. Read-only here." }, "slug": { "type": [ "string", "null" ], "description": "The booking page address of the product." }, "is_active": { "type": "boolean" }, "cover_photo_url": { "type": [ "string", "null" ] }, "gallery": { "type": "array", "items": { "type": "string" } }, "reminder": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "type": { "type": "string" }, "hours_before": { "type": "integer" }, "message_template": { "type": [ "string", "null" ] } } }, "confirmation": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "message_template": { "type": [ "string", "null" ] } } }, "show_notes": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ProductInput": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255, "example": "60-minute strategy session" }, "description": { "type": "string" }, "category_id": { "type": [ "integer", "null" ], "description": "One of your categories, or null for none." }, "price": { "type": "number", "example": 150, "description": "One-off price, decimal." }, "pricing_type": { "type": "string", "enum": [ "once_off", "recurring", "both" ], "default": "once_off" }, "recurring_price": { "type": "number" }, "recurring_interval": { "type": "string", "enum": [ "weekly", "monthly", "yearly" ], "default": "monthly" }, "is_active": { "type": "boolean", "default": true }, "reminder_enabled": { "type": "boolean" }, "reminder_type": { "type": "string", "enum": [ "email", "sms", "both" ] }, "reminder_hours_before": { "type": "integer" }, "reminder_message_template": { "type": "string" }, "confirmation_enabled": { "type": "boolean" }, "confirmation_message_template": { "type": "string" }, "show_notes": { "type": "boolean", "description": "Show the notes box on the booking form." } } }, "ProductPatch": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "example": "60-minute strategy session" }, "description": { "type": "string" }, "category_id": { "type": [ "integer", "null" ], "description": "One of your categories, or null for none." }, "price": { "type": "number", "example": 150, "description": "One-off price, decimal." }, "pricing_type": { "type": "string", "enum": [ "once_off", "recurring", "both" ], "default": "once_off" }, "recurring_price": { "type": "number" }, "recurring_interval": { "type": "string", "enum": [ "weekly", "monthly", "yearly" ], "default": "monthly" }, "is_active": { "type": "boolean", "default": true }, "reminder_enabled": { "type": "boolean" }, "reminder_type": { "type": "string", "enum": [ "email", "sms", "both" ] }, "reminder_hours_before": { "type": "integer" }, "reminder_message_template": { "type": "string" }, "confirmation_enabled": { "type": "boolean" }, "confirmation_message_template": { "type": "string" }, "show_notes": { "type": "boolean", "description": "Show the notes box on the booking form." } } }, "ProductSchedule": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "one_off", "recurring" ] }, "date": { "type": [ "string", "null" ], "format": "date", "description": "one_off only." }, "day": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 6, "description": "recurring only: 0 = Sunday … 6 = Saturday (day names are accepted on input)." }, "start_time": { "type": "string", "example": "09:00" }, "end_time": { "type": "string", "example": "17:00" } } }, "ProductSchedulesInput": { "type": "object", "required": [ "schedules" ], "properties": { "schedules": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "one_off", "recurring" ] }, "date": { "type": [ "string", "null" ], "format": "date", "description": "one_off only." }, "day": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 6, "description": "recurring only: 0 = Sunday … 6 = Saturday (day names are accepted on input)." }, "start_time": { "type": "string", "example": "09:00" }, "end_time": { "type": "string", "example": "17:00" } } }, "description": "Replaces every schedule of the product; [] clears them." } } }, "ProductCategory": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "display_order": { "type": "integer" }, "is_active": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ProductCategoryInput": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string" }, "display_order": { "type": "integer" }, "is_active": { "type": "boolean" } } }, "ProductCategoryPatch": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string" }, "display_order": { "type": "integer" }, "is_active": { "type": "boolean" } } }, "Package": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "pricing_type": { "type": "string", "enum": [ "once_off", "recurring", "both" ] }, "once_off_price": { "type": "number" }, "recurring_price": { "type": "number" }, "recurring_interval": { "type": "string" }, "quantity_limit": { "type": [ "integer", "null" ] }, "quantity_available": { "type": [ "integer", "null" ] }, "end_date": { "type": [ "string", "null" ], "format": "date" }, "is_active": { "type": "boolean" }, "is_available": { "type": "boolean", "description": "Active, not sold out and not past its end date." }, "display_order": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "integer" }, "product_name": { "type": "string" }, "quantity": { "type": "integer" }, "unit_price": { "type": [ "number", "null" ] }, "display_order": { "type": "integer" } } } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "PackageInput": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255, "example": "Launch bundle" }, "description": { "type": "string" }, "pricing_type": { "type": "string", "enum": [ "once_off", "recurring", "both" ], "default": "once_off" }, "once_off_price": { "type": "number" }, "recurring_price": { "type": "number" }, "recurring_interval": { "type": "string", "enum": [ "weekly", "monthly", "yearly" ], "default": "monthly" }, "quantity_limit": { "type": [ "integer", "null" ], "description": "How many can be sold; null = unlimited." }, "end_date": { "type": [ "string", "null" ], "format": "date", "description": "Last day on sale; null = no end." }, "is_active": { "type": "boolean", "default": true }, "display_order": { "type": "integer" }, "items": { "type": "array", "description": "Replaces every item. Each product_id must be one of your products.", "items": { "type": "object", "required": [ "product_id" ], "properties": { "product_id": { "type": "integer" }, "quantity": { "type": "integer", "default": 1 }, "display_order": { "type": "integer" } } } } } }, "PackagePatch": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "example": "Launch bundle" }, "description": { "type": "string" }, "pricing_type": { "type": "string", "enum": [ "once_off", "recurring", "both" ], "default": "once_off" }, "once_off_price": { "type": "number" }, "recurring_price": { "type": "number" }, "recurring_interval": { "type": "string", "enum": [ "weekly", "monthly", "yearly" ], "default": "monthly" }, "quantity_limit": { "type": [ "integer", "null" ], "description": "How many can be sold; null = unlimited." }, "quantity_available": { "type": [ "integer", "null" ], "description": "PATCH only: what is left (defaults to quantity_limit)." }, "end_date": { "type": [ "string", "null" ], "format": "date", "description": "Last day on sale; null = no end." }, "is_active": { "type": "boolean", "default": true }, "display_order": { "type": "integer" }, "items": { "type": "array", "description": "Replaces every item. Each product_id must be one of your products.", "items": { "type": "object", "required": [ "product_id" ], "properties": { "product_id": { "type": "integer" }, "quantity": { "type": "integer", "default": 1 }, "display_order": { "type": "integer" } } } } } }, "Coupon": { "type": "object", "properties": { "id": { "type": "integer", "example": 7 }, "code": { "type": "string", "example": "SPRING20" }, "discount_type": { "type": "string", "enum": [ "percentage", "fixed_amount" ] }, "discount_value": { "type": "number" }, "apply_to": { "type": "string", "enum": [ "subtotal", "total" ] }, "start_date": { "type": [ "string", "null" ], "format": "date" }, "end_date": { "type": [ "string", "null" ], "format": "date" }, "usage_limit": { "type": [ "integer", "null" ] }, "usage_count": { "type": "integer" }, "is_active": { "type": "boolean" }, "is_valid_now": { "type": "boolean", "description": "Active, within its dates and under its limit." }, "product_ids": { "type": "array", "items": { "type": "integer" }, "description": "[] = every product." }, "customer_emails": { "type": "array", "items": { "type": "string" }, "description": "[] = everyone." }, "coupon_type": { "type": [ "string", "null" ], "example": "once_off" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "CouponInput": { "type": "object", "required": [ "code", "discount_type", "discount_value" ], "properties": { "code": { "type": "string", "maxLength": 50, "example": "SPRING20", "description": "Stored upper-case; unique per business. Create only." }, "discount_type": { "type": "string", "enum": [ "percentage", "fixed_amount" ] }, "discount_value": { "type": "number", "example": 20, "description": "Percent (0–100) or an amount in the business currency." }, "apply_to": { "type": "string", "enum": [ "subtotal", "total" ], "default": "subtotal" }, "start_date": { "type": [ "string", "null" ], "format": "date" }, "end_date": { "type": [ "string", "null" ], "format": "date" }, "usage_limit": { "type": [ "integer", "null" ], "description": "Total redemptions allowed; null or 0 = unlimited." }, "is_active": { "type": "boolean", "default": true }, "product_ids": { "type": "array", "items": { "type": "integer" }, "description": "Limit it to these products of yours; [] = every product." }, "customer_emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Limit it to these customers; [] = everyone." } } }, "CouponPatch": { "type": "object", "description": "Send only what changes. The code cannot be changed.", "properties": { "discount_type": { "type": "string", "enum": [ "percentage", "fixed_amount" ] }, "discount_value": { "type": "number", "example": 20, "description": "Percent (0–100) or an amount in the business currency." }, "apply_to": { "type": "string", "enum": [ "subtotal", "total" ], "default": "subtotal" }, "start_date": { "type": [ "string", "null" ], "format": "date" }, "end_date": { "type": [ "string", "null" ], "format": "date" }, "usage_limit": { "type": [ "integer", "null" ], "description": "Total redemptions allowed; null or 0 = unlimited." }, "is_active": { "type": "boolean", "default": true }, "product_ids": { "type": "array", "items": { "type": "integer" }, "description": "Limit it to these products of yours; [] = every product." }, "customer_emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Limit it to these customers; [] = everyone." } } }, "CouponUsage": { "type": "object", "properties": { "coupon_id": { "type": "integer" }, "code": { "type": "string" }, "total_uses": { "type": "integer" }, "total_discount_given": { "type": "number" }, "average_discount": { "type": "number" }, "first_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "recent": { "type": "array", "description": "The latest 100 redemptions, newest first.", "items": { "type": "object", "properties": { "booking_id": { "type": [ "integer", "null" ] }, "customer_email": { "type": "string" }, "original_amount": { "type": "number" }, "discount_amount": { "type": "number" }, "final_amount": { "type": "number" }, "used_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "InvoiceLineItem": { "type": "object", "properties": { "id": { "type": "integer" }, "product_id": { "type": [ "integer", "null" ] }, "description": { "type": "string" }, "quantity": { "type": "number" }, "unit_price": { "type": "number", "example": 120, "description": "Decimal, in the invoice currency." }, "line_total": { "type": "number", "example": 180, "description": "Decimal, in the invoice currency." }, "vat_rate": { "type": "number", "description": "Percent." }, "vat_amount": { "type": "number", "example": 41.4, "description": "Decimal, in the invoice currency." }, "sort_order": { "type": "integer" } } }, "InvoiceLineItemInput": { "type": "object", "description": "`description` or `product_id` is required.", "properties": { "description": { "type": "string", "maxLength": 255, "description": "Defaults to the product name when `product_id` is sent." }, "quantity": { "type": "number", "default": 1, "example": 1.5 }, "unit_price": { "type": "number", "example": 120, "description": "Decimal, VAT-exclusive. Defaults to the product price." }, "vat_rate": { "type": "number", "example": 23, "description": "Percent. Leave it out to let the VAT rules of the two countries decide at issue." }, "product_id": { "type": "integer", "description": "One of your products: copies its name and price onto the line." }, "sort_order": { "type": "integer" } } }, "InvoiceLineItemPatch": { "type": "object", "description": "Send only what changes.", "properties": { "description": { "type": "string", "maxLength": 255, "description": "Defaults to the product name when `product_id` is sent." }, "quantity": { "type": "number", "default": 1, "example": 1.5 }, "unit_price": { "type": "number", "example": 120, "description": "Decimal, VAT-exclusive. Defaults to the product price." }, "vat_rate": { "type": "number", "example": 23, "description": "Percent. Leave it out to let the VAT rules of the two countries decide at issue." }, "sort_order": { "type": "integer" } } }, "Invoice": { "type": "object", "properties": { "id": { "type": "integer", "example": 88 }, "number": { "type": [ "string", "null" ], "example": "INV-2026-0042", "description": "Given at issue; null on a draft." }, "status": { "type": "string", "enum": [ "draft", "open", "paid", "void", "uncollectible" ] }, "currency": { "type": "string", "example": "EUR" }, "client_id": { "type": [ "integer", "null" ], "description": "The contact billed (null for a booking receipt to a walk-in customer)." }, "bill_to": { "type": "object", "properties": { "name": { "type": "string" }, "company": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "vat_number": { "type": [ "string", "null" ] } } }, "invoice_date": { "type": [ "string", "null" ], "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "is_overdue": { "type": "boolean" }, "subtotal": { "type": "number", "example": 360, "description": "Decimal, in the invoice currency." }, "discount_amount": { "type": "number", "example": 0, "description": "Decimal, in the invoice currency." }, "coupon_code": { "type": [ "string", "null" ] }, "vat_amount": { "type": "number", "example": 82.8, "description": "Decimal, in the invoice currency." }, "vat_reverse_charge": { "type": "boolean" }, "total": { "type": "number", "example": 442.8, "description": "Decimal, in the invoice currency." }, "amount_paid": { "type": "number", "example": 0, "description": "Decimal, in the invoice currency." }, "balance": { "type": "number", "example": 442.8, "description": "Decimal, in the invoice currency." }, "memo": { "type": [ "string", "null" ] }, "has_pay_link": { "type": "boolean", "description": "An open invoice with a live pay link (GET /invoices/{id}/pay-link)." }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLineItem" } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "InvoiceInput": { "type": "object", "required": [ "client_id" ], "properties": { "client_id": { "type": "integer", "description": "The contact to bill (GET /contacts)." }, "memo": { "type": "string", "maxLength": 1000 }, "due_date": { "type": "string", "format": "date", "description": "Defaults to the invoice settings' payment terms." }, "currency": { "type": "string", "example": "EUR", "description": "ISO 4217; defaults to the business currency." }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLineItemInput" }, "description": "Optional lines to start with." } } }, "InvoicePatch": { "type": "object", "description": "Drafts only. Send only what changes.", "properties": { "memo": { "type": "string", "maxLength": 1000 }, "due_date": { "type": "string", "format": "date" } } }, "InvoiceIssueInput": { "type": "object", "properties": { "send_email": { "type": "boolean", "default": true, "description": "Email it (with the pay link) to the client now, as the panel does." } } }, "InvoiceSendInput": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invoice", "reminder" ], "default": "invoice", "description": "`invoice` sends it again; `reminder` chases payment." } } }, "InvoiceSendResult": { "type": "object", "properties": { "sent_to": { "type": [ "string", "null" ], "description": "null when the client has no email address (nothing was sent)." }, "pay_url": { "type": "string", "format": "uri", "description": "The new pay link. Every email carries a fresh one; earlier links stop working." }, "invoice": { "$ref": "#/components/schemas/Invoice" } } }, "InvoicePayment": { "type": "object", "properties": { "id": { "type": "integer" }, "provider": { "type": "string", "enum": [ "manual", "stripe", "revolut", "gocardless" ] }, "method": { "type": [ "string", "null" ], "example": "bank_transfer" }, "amount": { "type": "number", "example": 100, "description": "Decimal, in the invoice currency." }, "currency": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "succeeded", "failed", "refunded" ] }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "reference": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "InvoicePaymentInput": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "number", "example": 100, "description": "Decimal, in the invoice currency." }, "method": { "type": "string", "enum": [ "bank_transfer", "cash", "card", "cheque", "other" ], "default": "other" }, "paid_at": { "type": "string", "format": "date-time", "description": "Defaults to now." }, "notes": { "type": "string", "maxLength": 500 } } }, "InvoicePdf": { "type": "object", "properties": { "filename": { "type": "string", "example": "Invoice-INV-2026-0042.pdf" }, "content_type": { "type": "string", "example": "application/pdf" }, "size": { "type": "integer", "description": "Bytes, before encoding." }, "content_base64": { "type": "string", "description": "The PDF, base64-encoded." } } }, "InvoicePayLink": { "type": "object", "properties": { "url": { "type": [ "string", "null" ], "format": "uri", "description": "The live public pay page, or null when none is kept (POST /invoices/{id}/send mints and emails a new one)." } } }, "ProposalSection": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string", "enum": [ "text", "scope", "timeline", "pricing" ] }, "heading": { "type": [ "string", "null" ], "example": "Scope" }, "body": { "type": [ "string", "null" ], "description": "HTML for text sections; for `scope`, one item per line (\"- \" prefix = out of scope)." }, "sort_order": { "type": "integer" } } }, "ProposalItem": { "type": "object", "properties": { "id": { "type": "integer" }, "description": { "type": "string", "example": "Website design" }, "qty": { "type": "number", "example": 1 }, "unit_price": { "type": "number", "example": 4500 }, "amount": { "type": "number", "example": 4500 }, "is_optional": { "type": "boolean", "description": "Optional items are shown but not counted in the subtotal." }, "make_task": { "type": "boolean", "description": "On acceptance, a task is created for this item." }, "product_id": { "type": [ "integer", "null" ] }, "package_id": { "type": [ "integer", "null" ] }, "sort_order": { "type": "integer" } } }, "ProposalMilestone": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string", "example": "Design sign-off" }, "description": { "type": [ "string", "null" ] }, "offset_days": { "type": [ "integer", "null" ], "description": "Days after acceptance." }, "fixed_date": { "type": [ "string", "null" ], "format": "date" }, "sort_order": { "type": "integer" } } }, "ProposalSummary": { "type": "object", "properties": { "id": { "type": "integer", "example": 42 }, "number": { "type": [ "string", "null" ], "example": "PRO-2026-0007", "description": "Given the first time it is sent." }, "title": { "type": "string", "example": "Website redesign" }, "status": { "type": "string", "enum": [ "draft", "sent", "opened", "accepted", "declined", "expired" ] }, "client_id": { "type": "integer", "description": "The contact the proposal is for." }, "deal_id": { "type": [ "integer", "null" ], "description": "A contact (deal) marked won when the proposal is accepted." }, "discovery_id": { "type": [ "integer", "null" ] }, "currency": { "type": "string", "example": "EUR" }, "valid_until": { "type": [ "string", "null" ], "format": "date" }, "discount_type": { "type": "string", "enum": [ "none", "percent", "fixed" ] }, "discount_value": { "type": "number", "description": "A percentage for `percent`, a money amount for `fixed`.", "example": 10 }, "tax_rate": { "type": "number", "description": "VAT percentage.", "example": 23 }, "tax_mode": { "type": "string", "enum": [ "exclusive", "inclusive" ] }, "subtotal": { "type": "number", "example": 4500 }, "tax": { "type": "number", "example": 4500 }, "total": { "type": "number", "example": 4500 }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "opened_at": { "type": [ "string", "null" ], "format": "date-time" }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "accepted_by_name": { "type": [ "string", "null" ] }, "accepted_by_email": { "type": [ "string", "null" ] }, "declined_at": { "type": [ "string", "null" ], "format": "date-time" }, "declined_reason": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ], "description": "The project created on acceptance." }, "deposit_invoice_id": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Proposal": { "type": "object", "properties": { "id": { "type": "integer", "example": 42 }, "number": { "type": [ "string", "null" ], "example": "PRO-2026-0007", "description": "Given the first time it is sent." }, "title": { "type": "string", "example": "Website redesign" }, "status": { "type": "string", "enum": [ "draft", "sent", "opened", "accepted", "declined", "expired" ] }, "client_id": { "type": "integer", "description": "The contact the proposal is for." }, "deal_id": { "type": [ "integer", "null" ], "description": "A contact (deal) marked won when the proposal is accepted." }, "discovery_id": { "type": [ "integer", "null" ] }, "currency": { "type": "string", "example": "EUR" }, "valid_until": { "type": [ "string", "null" ], "format": "date" }, "discount_type": { "type": "string", "enum": [ "none", "percent", "fixed" ] }, "discount_value": { "type": "number", "description": "A percentage for `percent`, a money amount for `fixed`.", "example": 10 }, "tax_rate": { "type": "number", "description": "VAT percentage.", "example": 23 }, "tax_mode": { "type": "string", "enum": [ "exclusive", "inclusive" ] }, "subtotal": { "type": "number", "example": 4500 }, "tax": { "type": "number", "example": 4500 }, "total": { "type": "number", "example": 4500 }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "opened_at": { "type": [ "string", "null" ], "format": "date-time" }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "accepted_by_name": { "type": [ "string", "null" ] }, "accepted_by_email": { "type": [ "string", "null" ] }, "declined_at": { "type": [ "string", "null" ], "format": "date-time" }, "declined_reason": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ], "description": "The project created on acceptance." }, "deposit_invoice_id": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "intro": { "type": [ "string", "null" ], "description": "HTML." }, "terms": { "type": [ "string", "null" ], "description": "HTML." }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/ProposalSection" } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ProposalItem" } }, "milestones": { "type": "array", "items": { "$ref": "#/components/schemas/ProposalMilestone" } } } }, "ProposalSectionInput": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "scope", "timeline", "pricing" ], "default": "text" }, "heading": { "type": "string" }, "body": { "type": "string" } } }, "ProposalItemInput": { "type": "object", "required": [ "description" ], "properties": { "description": { "type": "string", "maxLength": 500 }, "qty": { "type": "number", "default": 1 }, "unit_price": { "type": "number", "default": 0 }, "is_optional": { "type": "boolean" }, "make_task": { "type": "boolean" }, "product_id": { "type": [ "integer", "null" ] }, "package_id": { "type": [ "integer", "null" ] } } }, "ProposalMilestoneInput": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "offset_days": { "type": [ "integer", "null" ] }, "fixed_date": { "type": [ "string", "null" ], "format": "date" } } }, "ProposalInput": { "type": "object", "required": [ "client_id", "title" ], "properties": { "client_id": { "type": "integer" }, "title": { "type": "string", "maxLength": 255 }, "currency": { "type": "string", "example": "EUR", "description": "ISO 4217. Defaults to the business currency." }, "valid_until": { "type": [ "string", "null" ], "format": "date" }, "deal_id": { "type": [ "integer", "null" ] }, "intro": { "type": "string", "description": "HTML." }, "terms": { "type": "string", "description": "HTML." }, "discount_type": { "type": "string", "enum": [ "none", "percent", "fixed" ] }, "discount_value": { "type": "number" }, "tax_rate": { "type": "number" }, "tax_mode": { "type": "string", "enum": [ "exclusive", "inclusive" ] }, "sections": { "type": "array", "description": "Replaces every section.", "items": { "$ref": "#/components/schemas/ProposalSectionInput" } }, "items": { "type": "array", "description": "Replaces every line item.", "items": { "$ref": "#/components/schemas/ProposalItemInput" } }, "milestones": { "type": "array", "description": "Replaces every milestone.", "items": { "$ref": "#/components/schemas/ProposalMilestoneInput" } }, "discovery_id": { "type": "integer", "description": "Link the proposal to a discovery." } } }, "ProposalPatch": { "type": "object", "properties": { "client_id": { "type": "integer" }, "title": { "type": "string", "maxLength": 255 }, "currency": { "type": "string", "example": "EUR", "description": "ISO 4217. Defaults to the business currency." }, "valid_until": { "type": [ "string", "null" ], "format": "date" }, "deal_id": { "type": [ "integer", "null" ] }, "intro": { "type": "string", "description": "HTML." }, "terms": { "type": "string", "description": "HTML." }, "discount_type": { "type": "string", "enum": [ "none", "percent", "fixed" ] }, "discount_value": { "type": "number" }, "tax_rate": { "type": "number" }, "tax_mode": { "type": "string", "enum": [ "exclusive", "inclusive" ] }, "sections": { "type": "array", "description": "Replaces every section.", "items": { "$ref": "#/components/schemas/ProposalSectionInput" } }, "items": { "type": "array", "description": "Replaces every line item.", "items": { "$ref": "#/components/schemas/ProposalItemInput" } }, "milestones": { "type": "array", "description": "Replaces every milestone.", "items": { "$ref": "#/components/schemas/ProposalMilestoneInput" } } } }, "ProposalSendInput": { "type": "object", "properties": { "send_email": { "type": "boolean", "default": true, "description": "Email the client the link, as the panel's Send does." } } }, "ProposalSent": { "allOf": [ { "$ref": "#/components/schemas/Proposal" }, { "type": "object", "properties": { "public_url": { "type": "string", "example": "https://app.digitalagency.tools/p/3f9a…", "description": "The client's link. Only ever returned here." }, "email_sent": { "type": "boolean" } } } ] }, "DepositInvoiceInput": { "type": "object", "required": [ "value" ], "properties": { "mode": { "type": "string", "enum": [ "percent", "fixed" ], "default": "percent" }, "value": { "type": "number", "description": "A percentage of the total, or a gross money amount.", "example": 25 } } }, "DepositInvoice": { "type": "object", "properties": { "invoice_id": { "type": "integer" }, "number": { "type": [ "string", "null" ] }, "pay_url": { "type": [ "string", "null" ], "description": "The client's pay link (only when just created)." }, "already_existed": { "type": "boolean", "description": "True when the proposal already had a deposit invoice; nothing new was issued." } } }, "ProposalPdf": { "type": "object", "properties": { "filename": { "type": "string", "example": "proposal-42.pdf" }, "content_type": { "type": "string", "example": "application/pdf" }, "size": { "type": "integer", "description": "Bytes." }, "content_base64": { "type": "string", "description": "The PDF, base64-encoded." } } }, "DiscoveryQuestion": { "type": "object", "properties": { "id": { "type": "integer" }, "question": { "type": "string" }, "why_it_matters": { "type": [ "string", "null" ] }, "answer": { "type": [ "string", "null" ] }, "is_answered": { "type": "boolean" }, "sort_order": { "type": "integer" } } }, "Discovery": { "type": "object", "properties": { "id": { "type": "integer", "example": 12 }, "title": { "type": "string", "example": "Byrne Bakeries — new site" }, "status": { "type": "string", "enum": [ "intake", "researched", "questions_ready", "meeting_done", "brief_ready" ] }, "client_id": { "type": [ "integer", "null" ] }, "lead_id": { "type": [ "integer", "null" ] }, "intake_submission_id": { "type": [ "integer", "null" ], "description": "The form submission it came from (GET /submissions/{id})." }, "raw_input": { "type": [ "string", "null" ], "description": "Notes, emails, transcripts — whatever you started from." }, "brief": { "type": [ "object", "null" ], "additionalProperties": true, "description": "The structured brief (summary, goals, deliverables, …)." }, "brief_summary": { "type": [ "string", "null" ] }, "research_notes": { "type": [ "string", "null" ] }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/DiscoveryQuestion" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "DiscoveryInput": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "maxLength": 255 }, "raw_input": { "type": "string" }, "client_id": { "type": "integer", "description": "A contact of this business." }, "intake_submission_id": { "type": "integer", "description": "A form submission of this business." } } }, "DiscoveryPatch": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255 }, "raw_input": { "type": "string" }, "brief": { "type": "object", "additionalProperties": true }, "brief_summary": { "type": "string" }, "research_notes": { "type": "string" }, "status": { "type": "string", "enum": [ "intake", "researched", "questions_ready", "meeting_done", "brief_ready" ] } } }, "DiscoveryProposalInput": { "type": "object", "properties": { "client_id": { "type": "integer", "description": "Who the proposal is for. Defaults to the discovery's client; required when it has none." } } }, "Ticket": { "type": "object", "properties": { "id": { "type": "integer", "example": 311 }, "number": { "type": "string", "example": "TK-20261105-004" }, "subject": { "type": "string", "example": "Contact form not sending" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "open", "pending", "resolved", "closed" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "client_id": { "type": [ "integer", "null" ], "description": "A contact." }, "project_id": { "type": [ "integer", "null" ] }, "category_id": { "type": [ "integer", "null" ], "description": "See GET /ticket-categories." }, "assignee_id": { "type": [ "integer", "null" ], "description": "A staff user (GET /staff)." }, "created_by": { "type": [ "integer", "null" ], "description": "The staff user who opened it; null when it came from a client (email, WhatsApp, the support form)." }, "tags": { "type": [ "string", "null" ] }, "last_reply_at": { "type": [ "string", "null" ], "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "TicketInput": { "type": "object", "required": [ "subject" ], "properties": { "subject": { "type": "string", "maxLength": 255 }, "description": { "type": "string" }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "client_id": { "type": [ "integer", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "category_id": { "type": [ "integer", "null" ] }, "assignee_id": { "type": [ "integer", "null" ] }, "tags": { "type": "string" } } }, "TicketPatch": { "type": "object", "properties": { "subject": { "type": "string", "maxLength": 255 }, "description": { "type": "string" }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "client_id": { "type": [ "integer", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "category_id": { "type": [ "integer", "null" ] }, "assignee_id": { "type": [ "integer", "null" ] }, "tags": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "open", "pending", "resolved", "closed" ] } } }, "TicketReply": { "type": "object", "properties": { "id": { "type": "integer" }, "ticket_id": { "type": "integer" }, "sender_type": { "type": "string", "enum": [ "agent", "client", "system" ] }, "sender_id": { "type": [ "integer", "null" ], "description": "The staff user, for agent replies." }, "sender_name": { "type": [ "string", "null" ] }, "sender_email": { "type": [ "string", "null" ] }, "body": { "type": "string" }, "html": { "type": [ "string", "null" ] }, "is_internal_note": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "TicketReplyInput": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Plain text." }, "is_internal_note": { "type": "boolean", "default": false, "description": "Only your team sees it; never sent to the client." }, "status": { "type": "string", "enum": [ "new", "open", "pending", "resolved", "closed" ], "description": "Optionally move the ticket at the same time (e.g. `pending`)." } } }, "TicketCategory": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string", "example": "Billing" }, "description": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ], "example": "#6c757d" }, "default_priority": { "type": [ "string", "null" ], "enum": [ "low", "medium", "high", "urgent" ] }, "is_active": { "type": "boolean" }, "sort_order": { "type": "integer" } } }, "FormField": { "type": "object", "additionalProperties": true, "properties": { "name": { "type": "string", "example": "email", "description": "The key the answer is stored under in a submission's `data`." }, "type": { "type": "string", "example": "email", "description": "text, textarea, email, phone, url, number, select, radio, checkbox, date, …" }, "label": { "type": "string", "example": "Email Address" }, "required": { "type": "boolean" }, "options": { "type": "array", "items": { "type": "string" }, "description": "For select, radio and checkbox fields." } } }, "FormSection": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/FormField" } } } }, "FormSummary": { "type": "object", "properties": { "id": { "type": "integer", "example": 7 }, "name": { "type": "string", "example": "New website enquiry" }, "description": { "type": [ "string", "null" ] }, "slug": { "type": "string", "example": "new-website-enquiry" }, "public_url": { "type": "string", "example": "https://app.digitalagency.tools/intake/new-website-enquiry" }, "is_active": { "type": "boolean", "description": "Inactive forms do not accept submissions." }, "client_id": { "type": [ "integer", "null" ], "description": "Set when the form is for one contact; every submission is filed under them." }, "submission_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Form": { "type": "object", "properties": { "id": { "type": "integer", "example": 7 }, "name": { "type": "string", "example": "New website enquiry" }, "description": { "type": [ "string", "null" ] }, "slug": { "type": "string", "example": "new-website-enquiry" }, "public_url": { "type": "string", "example": "https://app.digitalagency.tools/intake/new-website-enquiry" }, "is_active": { "type": "boolean", "description": "Inactive forms do not accept submissions." }, "client_id": { "type": [ "integer", "null" ], "description": "Set when the form is for one contact; every submission is filed under them." }, "submission_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/FormSection" }, "description": "The field definitions, in order." } } }, "FormSubmission": { "type": "object", "properties": { "id": { "type": "integer", "example": 501 }, "form_id": { "type": "integer" }, "client_id": { "type": [ "integer", "null" ], "description": "The contact it was filed under (matched or created by email)." }, "status": { "type": "string", "enum": [ "draft", "submitted", "processed", "archived" ] }, "data": { "type": "object", "additionalProperties": true, "description": "Answers keyed by field `name`." }, "notes": { "type": [ "string", "null" ] }, "submitted_at": { "type": "string", "format": "date-time" }, "processed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Subscriber": { "type": "object", "properties": { "id": { "type": "integer", "example": 88 }, "email": { "type": "string", "format": "email" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "source": { "type": [ "string", "null" ], "example": "website", "description": "`website`, `manual`, `api`, …" }, "subscribed_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "SubscriberInput": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } }, "Campaign": { "type": "object", "properties": { "id": { "type": "integer", "example": 14 }, "title": { "type": "string", "example": "Autumn update" }, "content": { "type": "string", "description": "The body (plain text or simple HTML)." }, "cover_photo_url": { "type": [ "string", "null" ] }, "product_ids": { "type": "array", "items": { "type": "integer" }, "description": "Products featured under the body." }, "status": { "type": "string", "enum": [ "draft", "sent" ] }, "sent_count": { "type": "integer" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_by": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "CampaignInput": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "maxLength": 255 }, "content": { "type": "string" }, "cover_photo_url": { "type": "string", "description": "An https image URL." }, "product_ids": { "type": "array", "items": { "type": "integer" } } } }, "CampaignPatch": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255 }, "content": { "type": "string" }, "cover_photo_url": { "type": "string" }, "product_ids": { "type": "array", "items": { "type": "integer" } } } }, "CampaignSendResult": { "allOf": [ { "$ref": "#/components/schemas/Campaign" }, { "type": "object", "properties": { "failed_count": { "type": "integer", "description": "Subscribers the email could not be sent to." } } } ] }, "StaffMember": { "type": "object", "properties": { "id": { "type": "integer", "example": 17, "description": "The user id (use it as assignee_id on tickets and tasks)." }, "name": { "type": "string", "example": "Niamh Walsh" }, "email": { "type": "string", "format": "email" }, "phone": { "type": [ "string", "null" ] }, "role": { "type": "string", "enum": [ "owner", "admin", "member", "client" ] }, "last_active_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "StaffInput": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "admin", "member", "client" ], "default": "admin" } } }, "StaffPatch": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "admin", "member", "client" ] } } }, "Notification": { "type": "object", "properties": { "id": { "type": "integer", "example": 9021 }, "event": { "type": "string", "example": "proposal.accepted" }, "title": { "type": "string", "example": "Proposal accepted: Website redesign" }, "body": { "type": "string" }, "url": { "type": [ "string", "null" ], "example": "/projects/77", "description": "App-relative link into the panel." }, "severity": { "type": "string", "enum": [ "crit", "warn", "ok", "info" ] }, "is_read": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "read_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "NotificationsMarked": { "type": "object", "properties": { "marked": { "type": "integer", "description": "How many were unread and are now read." } } }, "ApiKey": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string", "example": "Zapier" }, "prefix": { "type": "string", "example": "dak1.3f9a2c1b", "description": "The non-secret part, shown in the panel to tell keys apart." }, "scope": { "type": "string", "enum": [ "read", "write", "admin" ] }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "ApiKeyCreated": { "allOf": [ { "$ref": "#/components/schemas/ApiKey" }, { "type": "object", "properties": { "key": { "type": "string", "example": "dak1.3f9a2c1b.0c6f…", "description": "The full key. Only ever returned here." } } } ] }, "ApiKeyInput": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 100 }, "scope": { "type": "string", "enum": [ "read", "write", "admin" ], "default": "read" } } }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string", "example": "https://hooks.example.com/agency" }, "description": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" }, "example": [ "invoice.paid", "proposal.accepted" ] }, "is_active": { "type": "boolean" }, "failure_count": { "type": "integer" }, "disabled_reason": { "type": [ "string", "null" ] }, "last_delivery_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "WebhookEndpointCreated": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpoint" }, { "type": "object", "properties": { "secret": { "type": "string", "example": "whsec_…", "description": "Signing secret. Only returned on create and on rotate." } } } ] }, "WebhookEndpointInput": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "description": "https only, port 443, a public hostname." }, "events": { "type": "array", "items": { "type": "string" }, "description": "Event types, or `[\"*\"]` for all." }, "description": { "type": "string" }, "is_active": { "type": "boolean", "description": "Update only. Re-enabling resets the failure count." } } }, "WebhookSecret": { "type": "object", "properties": { "secret": { "type": "string" } } }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "integer" }, "endpoint_id": { "type": "integer" }, "event_id": { "type": "string", "example": "evt_6b1f…" }, "event_type": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "delivered", "failed" ] }, "attempts": { "type": "integer" }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "response_code": { "type": [ "integer", "null" ] }, "response_excerpt": { "type": [ "string", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "EventType": { "type": "object", "properties": { "type": { "type": "string", "example": "invoice.paid" }, "description": { "type": "string" } } } } } }