{ "openapi": "3.1.0", "info": { "title": "FoPost API", "version": "1.0.0", "description": "REST API for FoPost — schedule, publish, and analyze social media content across every connected platform.\n\n## Authentication\n\nProgrammatic access uses an API key sent in the `X-API-Key` header. Keys are created in the FoPost dashboard under **Settings → API Keys** and are limited to the scopes granted at creation. Requests from the FoPost dashboard use a JWT bearer token instead (`Authorization: Bearer `), which implicitly carries all scopes. Either method works on every endpoint in this document unless noted otherwise.\n\n## Scopes\n\nEach operation lists its required scope (also machine-readable as `x-fopost-scope`): `posts` (includes publishing, deliveries, and media), `workspaces`, `accounts`, `labels`, `webhooks`, `analytics`, `automations`.\n\n## Responses\n\nEvery key in a response body and every query parameter is snake_case; request bodies keep the field names documented on each operation. The ads endpoints (`/v1/ads/*`) are the one exception and keep camelCase keys. A single resource is returned as the object itself (`201` on create); a collection is `{ \"data\": [...], \"meta\": {...} }`. A success with nothing to return is `204` with an empty body.\n\n## Errors\n\nErrors return `{ \"error\": \"\", \"message\": \"\" }` with a matching HTTP status, including an unknown route (`404 not_found`) and a server fault (`500 internal_error`). `error` is a stable snake_case code; `message` is for humans and may change. Some errors include additional context fields. A feature that is not set up on this deployment answers `503 not_configured`; a malformed answer from an upstream provider answers `502 upstream_error`.\n\n## Request ids\n\nEvery response carries an `X-Request-Id` header. Quote it when contacting support about a specific request.\n\n## Rate limiting\n\nRequests are rate limited per API key, per minute, with a ceiling set by the plan behind the key. Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`; exceeding the limit returns `429` with error code `too_many_requests`, a `retry_after` field and a `Retry-After` header. Mutating endpoints additionally require an active subscription and return `403` with error code `subscription_required` without one.\n\n## Pagination\n\nOffset-paged lists accept `page` and `per_page` (1 to 100) and return `meta: { page, per_page, total, total_pages }`. Cursor-paged lists return `meta: { next_cursor, has_more }`; pass `next_cursor` back in the cursor parameter the operation documents until `has_more` is false. Lists that do not paginate return `{ \"data\": [...] }` with no `meta`.", "contact": { "name": "FoPost Support", "url": "https://fopost.com/contact" }, "license": { "name": "Proprietary", "url": "https://fopost.com/terms" } }, "servers": [ { "url": "https://api.fopost.com", "description": "Production" } ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] }, { "OAuth2": [] } ], "tags": [ { "name": "Posts", "description": "Create and manage posts" }, { "name": "Publishing", "description": "Deliver posts to connected platforms" }, { "name": "Validation", "description": "Check content and media before a post exists" }, { "name": "Posting Queue", "description": "Recurring posting slots and queue placement" }, { "name": "Workspaces", "description": "Organize accounts and content" }, { "name": "Accounts", "description": "Connected social accounts" }, { "name": "Communities", "description": "X (Twitter) communities" }, { "name": "Google Business", "description": "Manage a connected Google Business Profile location" }, { "name": "Labels", "description": "Tag and organize posts" }, { "name": "Webhooks", "description": "Event notifications for your endpoints" }, { "name": "Analytics", "description": "Performance metrics and audience insights" }, { "name": "Automations", "description": "Trigger-driven publishing workflows" }, { "name": "Inbox", "description": "Comments, mentions and messages on connected accounts" }, { "name": "Contacts", "description": "The people behind the inbox, and the fields kept about them" }, { "name": "Blog", "description": "Long-form articles written for your own website: keyword plan, drafts, review and publishing" }, { "name": "Broadcasts", "description": "One message into many conversations, and drip sequences" }, { "name": "Knowledge", "description": "The workspace's own answers, pages and files, used to ground replies" }, { "name": "Ads", "description": "Meta ads, audiences and lead forms" }, { "name": "Media", "description": "Upload and manage media files" }, { "name": "API", "description": "API metadata" }, { "name": "OAuth", "description": "OAuth 2.1 for third-party apps" } ], "paths": { "/v1/openapi.json": { "get": { "operationId": "getOpenApiSpec", "summary": "Get this OpenAPI document", "tags": [ "API" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "description": "The OpenAPI document" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Returns the OpenAPI 3.1 description of the FoPost public API. No auth required.", "security": [] } }, "/.well-known/oauth-authorization-server": { "get": { "operationId": "getAuthorizationServerMetadata", "summary": "Authorization server metadata", "tags": [ "OAuth" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "issuer": { "type": "string" }, "authorization_endpoint": { "type": "string" }, "token_endpoint": { "type": "string" }, "revocation_endpoint": { "type": "string" }, "registration_endpoint": { "type": "string" }, "response_types_supported": { "type": "array", "items": { "type": "string" } }, "response_modes_supported": { "type": "array", "items": { "type": "string" } }, "grant_types_supported": { "type": "array", "items": { "type": "string" } }, "code_challenge_methods_supported": { "type": "array", "items": { "type": "string" } }, "token_endpoint_auth_methods_supported": { "type": "array", "items": { "type": "string" } }, "revocation_endpoint_auth_methods_supported": { "type": "array", "items": { "type": "string" } }, "scopes_supported": { "type": "array", "items": { "type": "string" } } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "RFC 8414 discovery document: endpoint URLs, supported grant types, PKCE methods and scopes. No auth required.", "security": [] } }, "/oauth/authorize": { "get": { "operationId": "oauthAuthorize", "summary": "Start an authorization", "tags": [ "OAuth" ], "responses": { "302": { "description": "Redirect to the consent screen, or to redirect_uri with an error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "RFC 6749 error (`invalid_client` for an unknown client_id, `invalid_request` for an unregistered redirect_uri)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error", "error_description" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Send the user here in a browser. After validating the client and redirect_uri the user signs in, picks a workspace and approves the scopes; the browser is then sent to `redirect_uri` with `code` and `state`, or with `error=access_denied`. PKCE with S256 is required. Errors about the client or redirect_uri answer 400 here instead of redirecting.", "parameters": [ { "name": "response_type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "code" ] } }, { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "redirect_uri", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "Exactly one of the URIs registered for the client" }, { "name": "scope", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Space-separated scopes, the same names as API-key scopes" }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Echoed back unchanged" }, { "name": "code_challenge", "in": "query", "required": true, "schema": { "type": "string" }, "description": "BASE64URL(SHA256(code_verifier))" }, { "name": "code_challenge_method", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "S256" ] } } ], "security": [] } }, "/oauth/token": { "post": { "operationId": "oauthToken", "summary": "Exchange a code or refresh token", "tags": [ "OAuth" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "expires_in": { "type": "integer" }, "refresh_token": { "type": "string" }, "scope": { "type": "string" } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "RFC 6749 error: invalid_grant (wrong verifier, used or expired code), invalid_scope, unsupported_grant_type", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error", "error_description" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "invalid_client", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error", "error_description" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "`grant_type=authorization_code` takes `code`, `redirect_uri`, `code_verifier` and `client_id`; `grant_type=refresh_token` takes `refresh_token` and `client_id`. A confidential client also sends `client_secret` (or HTTP Basic). Refresh tokens rotate on every use. Access tokens last one hour and go in `Authorization: Bearer`; they carry the approved scopes and are confined to the approved workspace.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "grant_type", "client_id" ], "properties": { "grant_type": { "type": "string", "enum": [ "authorization_code", "refresh_token" ] }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "code": { "type": "string" }, "redirect_uri": { "type": "string", "format": "uri" }, "code_verifier": { "type": "string", "minLength": 43, "maxLength": 128 }, "refresh_token": { "type": "string" } } } } } }, "security": [] } }, "/oauth/revoke": { "post": { "operationId": "oauthRevoke", "summary": "Revoke a token", "tags": [ "OAuth" ], "responses": { "200": { "description": "Revoked, or nothing to revoke", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "invalid_client", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error", "error_description" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "RFC 7009. Revokes the grant behind an access or refresh token; answers 200 whether or not the token existed. Requires `client_id` (and `client_secret` for a confidential client).", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "token", "client_id" ], "properties": { "token": { "type": "string" }, "token_type_hint": { "type": "string", "enum": [ "access_token", "refresh_token" ] }, "client_id": { "type": "string" }, "client_secret": { "type": "string" } } } } } }, "security": [] } }, "/oauth/register": { "post": { "operationId": "oauthRegister", "summary": "Register a client", "tags": [ "OAuth" ], "responses": { "201": { "description": "Registered", "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "type": "string" }, "client_secret": { "type": "string", "description": "Only for a confidential client; shown once" }, "client_name": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "client_uri": { "type": "string" }, "token_endpoint_auth_method": { "type": "string" }, "grant_types": { "type": "array", "items": { "type": "string" } }, "response_types": { "type": "array", "items": { "type": "string" } }, "client_id_issued_at": { "type": "integer" } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "RFC 7591 `invalid_client_metadata`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error", "error_description" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "RFC 7591 registration for signed-in developers: use your API key. The client is owned by your account. `client_uri` is your site; every redirect URI must be https on that host or a subdomain of it (loopback http is allowed for native and local clients) and is matched exactly. The client name may not use the product name. `token_endpoint_auth_method` defaults to `none` (a public client, PKCE only); `client_secret_basic` or `client_secret_post` issues a secret that is shown once.\n\nMCP clients may register without a credential when every redirect URI is loopback or on a supported MCP client host; `client_uri` is then optional and the client has no owner.\n\nRequires the `workspaces` scope when using an API key.", "x-fopost-scope": "workspaces", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "client_name", "redirect_uris", "client_uri" ], "properties": { "client_name": { "type": "string", "maxLength": 100 }, "redirect_uris": { "type": "array", "items": { "type": "string", "format": "uri" }, "minItems": 1, "maxItems": 10 }, "client_uri": { "type": "string", "format": "uri" }, "token_endpoint_auth_method": { "type": "string", "enum": [ "none", "client_secret_basic", "client_secret_post" ] } } } } } } } }, "/v1/posts": { "get": { "operationId": "listPosts", "summary": "List posts", "tags": [ "Posts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostListResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Lists posts across all workspaces the user belongs to, newest first. All filters are optional and combine with AND semantics.\n\nRequires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 30, "minimum": 1, "maximum": 100 } }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to one workspace" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "scheduled", "publishing", "published", "partially_failed", "failed", "cancelled", "unpublished" ] } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Full-text match against post content" }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated platform names (e.g. `twitter,linkedin`)" }, { "name": "label", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated label uuids" }, { "name": "account_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated account uuids" }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Only posts created on this day (YYYY-MM-DD, UTC)" }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Range start (inclusive). Scheduled posts filter on schedule time, drafts on creation time." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Range end (exclusive)" }, { "name": "unscheduled", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true" ] }, "description": "Pass `true` for drafts with no `schedule_at`" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "oldest" ] }, "description": "Pass `oldest` for ascending order; default is newest first" } ] }, "post": { "operationId": "createPost", "summary": "Create a post", "tags": [ "Posts" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "description": "A file is over the account ceiling (`file_too_large`, with `max_file_bytes`) or the storage allowance (`storage_limit_reached`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Creates a draft or scheduled post targeting one or more connected accounts. Content is an ordered list of blocks (threads use multiple blocks).\n\nRequires the `posts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "posts", "requestBody": { "required": true, "description": "JSON, or `multipart/form-data` with the same JSON in a `post` field and up to 5 files under `files`. Files are stored in the workspace library and attached to the first content block. Multipart carries files up to 100 MB each; a larger file goes through direct upload and is attached by url.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePostRequest" } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "post": { "type": "string", "description": "The JSON body, as a string" }, "files": { "type": "array", "items": { "type": "string", "format": "binary" } } }, "required": [ "post" ] } } } } } }, "/v1/posts/{id}": { "get": { "operationId": "getPost", "summary": "Get a post", "tags": [ "Posts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Post id" } ] }, "put": { "operationId": "updatePost", "summary": "Update a post", "tags": [ "Posts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Post cannot be updated: it is publishing or cancelled, a published post was given accounts or a schedule, or one of its networks cannot edit a live post (`unsupported_platforms` lists them)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "413": { "description": "A file is over the account ceiling (`file_too_large`, with `max_file_bytes`) or the storage allowance (`storage_limit_reached`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Arrays (`content`, `accounts`, `labels`, `settings`) are replaced wholesale when provided. A draft, scheduled or pending-approval post takes any change. A published post takes a content change only (`content`, `title`, `settings`, `labels`, `internal_title`, `summary`), and only when every network it is live on can edit in place (see `remote_edit` on the post accounts); the change is then pushed to each network and reported in `remote_edits`. Reaching a network needs the `publish` scope as well. A published post on a network that cannot edit answers 409 with `unsupported_platforms`.\n\nRequires the `posts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Post id" } ], "requestBody": { "required": true, "description": "JSON, or `multipart/form-data` with the same JSON in a `post` field and up to 5 files under `files`, which join the first content block (of the new `content`, or of the stored content when none is sent). Multipart carries files up to 100 MB each.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePostRequest" } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "post": { "type": "string", "description": "The JSON body, as a string" }, "files": { "type": "array", "items": { "type": "string", "format": "binary" } } }, "required": [ "post" ] } } } } }, "delete": { "operationId": "deletePost", "summary": "Delete a post", "tags": [ "Posts" ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostDeleteResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Soft-deletes the post. Already-published platform posts stay up unless `remove_from_platform` is set, which also asks each network that supports it (see `remote_delete` on the post accounts) to take the post down. Reaching a network needs the `publish` scope as well.\n\nRequires the `posts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Post id" }, { "name": "remove_from_platform", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Also delete the published post from the networks that support it" } ] } }, "/v1/queue/slots": { "get": { "operationId": "listQueueSlots", "summary": "List posting slots", "tags": [ "Posting Queue" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/QueueSlot" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "The recurring weekly slots of a workspace, ordered by weekday and time.\n\nRequires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "parameters": [ { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "post": { "operationId": "createQueueSlot", "summary": "Add a posting slot", "tags": [ "Posting Queue" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueSlot" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Adds a weekly slot. Omit `account_id` for a slot every account in the workspace shares.\n\nRequires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQueueSlotRequest" } } } } } }, "/v1/queue/slots/{id}": { "put": { "operationId": "updateQueueSlot", "summary": "Change a posting slot", "tags": [ "Posting Queue" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueSlotUpdated" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Changes a slot. Queued posts whose time no longer matches a free occurrence are moved to the next one and listed in `moved`.\n\nRequires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Slot id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateQueueSlotRequest" } } } } }, "delete": { "operationId": "deleteQueueSlot", "summary": "Remove a posting slot", "tags": [ "Posting Queue" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueSlotDeleted" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Removes a slot. Queued posts that sat on it move to the next free occurrence and are listed in `moved`.\n\nRequires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Slot id" } ] } }, "/v1/queue/next": { "get": { "operationId": "getQueueNext", "summary": "Next free slot", "tags": [ "Posting Queue" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueNext" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "The time a post added to the queue now would get. Pass `account_id` to ask for one account; without it the answer is the next free occurrence of any slot.\n\nRequires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "parameters": [ { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "account_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/queue/preview": { "get": { "operationId": "previewQueue", "summary": "Preview upcoming slots", "tags": [ "Posting Queue" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string", "format": "date-time" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "The next free occurrences in order, as a post-by-post preview of the queue.\n\nRequires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "parameters": [ { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "account_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "default": 5, "minimum": 1, "maximum": 20 } } ] } }, "/v1/posts/{id}/publish": { "post": { "operationId": "publishPost", "summary": "Publish a post", "tags": [ "Publishing" ], "responses": { "200": { "description": "Dry run result (only with `options.dryRun`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRunResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "202": { "description": "Deliveries queued, or the post held for approval (`held: true`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Post is not in a draft or scheduled state, or is awaiting approval (`approval_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "422": { "description": "All target accounts have expired/revoked credentials (`health_check_failed`, with an empty `health_warnings`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Queues delivery of a draft or scheduled post to its assigned accounts (or the `accountIds` subset). Accounts with expired or revoked credentials are failed immediately; degraded accounts publish with a warning. Delivery is asynchronous — poll the deliveries endpoint or subscribe to webhooks for the outcome. With `options.dryRun` the request validates and returns the target accounts without publishing (200 instead of 202).\n\nRequires the `posts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Post id" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishPostRequest" } } } } } }, "/v1/posts/{id}/retry": { "post": { "operationId": "retryPost", "summary": "Retry failed deliveries", "tags": [ "Publishing" ], "responses": { "200": { "description": "Retries queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Post state does not allow retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "422": { "description": "Every selected delivery exceeded the retry limit (`retry_limit_exceeded`, with `exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Re-queues failed deliveries of a failed, partially failed, or published post. Resending to already-published accounts requires `includePublished: true`. Deliveries past the retry limit are reported in `exceeded` and skipped.\n\nRequires the `posts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Post id" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryPostRequest" } } } } } }, "/v1/posts/{id}/cancel": { "post": { "operationId": "cancelPost", "summary": "Cancel pending deliveries", "tags": [ "Publishing" ], "responses": { "200": { "description": "Deliveries cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Cancels pending, queued, or delayed deliveries (optionally limited to `accountIds`) and recalculates the post status. Send no body, or `{}`, to cancel all.\n\nRequires the `posts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Post id" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelPostRequest" } } } } } }, "/v1/posts/{id}/unpublish": { "post": { "operationId": "unpublishPost", "summary": "Take a published post down everywhere", "tags": [ "Publishing" ], "responses": { "200": { "description": "Deliveries taken down", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnpublishResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Post is not published, or a network cannot delete a live post", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Deletes the post on every network it is live on and marks each delivery `unpublished`; the post stays as a record. Refused as a whole with 409 and `unsupported_platforms` when one of those networks cannot delete a live post (see `remote_delete` on the post accounts). A network that refuses at the time keeps its delivery published and answers `removed: false`.\n\nRequires the `publish` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "publish", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Post id" } ] } }, "/v1/posts/{id}/preflight": { "post": { "operationId": "preflightPost", "summary": "Preflight-check a post", "tags": [ "Publishing" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreflightResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Checks each assigned account for hard blockers (`issues`) and returns advisory per-platform content quality signals. Signals never block publishing.\n\nRequires the `posts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Post id" } ] } }, "/v1/validate/post": { "post": { "operationId": "validatePost", "summary": "Validate content for a set of platforms", "tags": [ "Validation" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidatePostResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "The same checks as preflight, for content that has not been saved as a post. Returns hard blockers (`issues`) and advisory content quality signals per platform. Nothing is stored.\n\nRequires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidatePostRequest" } } } } } }, "/v1/validate/length": { "post": { "operationId": "validateLength", "summary": "Check text length against platform limits", "tags": [ "Validation" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateLengthResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Counts the text the way each platform does (some bill every link at a flat rate, some count bytes) and compares it with the platform limit.\n\nRequires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateLengthRequest" } } } } } }, "/v1/validate/media": { "post": { "operationId": "validateMedia", "summary": "Check a media file by URL", "tags": [ "Validation" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateMediaResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "The link could not be fetched (`fetch_failed`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Fetches the file and runs the upload checks on it: allowed type, bytes that match the declared type, and the size ceiling. The file is not stored. A URL that cannot be fetched, including one that points at a private address, is a `400`.\n\nRequires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateMediaRequest" } } } } } }, "/v1/posts/{id}/deliveries": { "get": { "operationId": "listDeliveries", "summary": "List deliveries for a post", "tags": [ "Publishing" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Returns the per-account delivery records, newest first.\n\nRequires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Post id" } ] } }, "/v1/posts/{id}/publish-runs": { "get": { "operationId": "listPostPublishRuns", "summary": "List publish runs for a post", "tags": [ "Publishing" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublishRun" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "The post’s publish history. Each run is one publish pass over the post and carries the attempts it made per account, with the permalink of anything that went live. Newest run first.\n\nRequires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Post id" } ] } }, "/v1/posts/{id}/duplicate": { "post": { "operationId": "duplicatePost", "summary": "Duplicate a post", "tags": [ "Posts" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" } }, "required": [ "id", "status" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Copies the post — content, target accounts, per-platform settings and labels — into a new draft in the same workspace. Schedule, approval and delivery state are not carried over.\n\nRequires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Post id" } ] } }, "/v1/posts/{id}/analytics": { "get": { "operationId": "getPostAnalytics", "summary": "Get analytics for a post", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostAnalyticsResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Aggregated metrics for a post across every platform it was delivered to, using the latest collected snapshot per platform post.\n\nRequires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Post id" } ] } }, "/v1/posts/bulk": { "post": { "operationId": "bulkUpdatePosts", "summary": "Bulk reschedule, relabel or delete posts", "tags": [ "Posts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "updated": { "type": "integer" }, "action": { "type": "string", "enum": [ "shift", "label", "delete" ] }, "mode": { "type": "string", "enum": [ "replace", "add", "remove" ] } }, "required": [ "updated", "action" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Applies one action to up to 200 posts in a single transaction. Every post is validated first: any id outside the workspace answers 404 and any post that is no longer draft or scheduled answers 409, in both cases without changing anything. `shift` moves each `schedule_at` by `offset_minutes` (negative moves earlier) and refuses offsets that land in the past; `label` applies `label_ids` with mode `replace` (an empty list clears), `add` or `remove`; `delete` soft-deletes the posts and cancels their queued deliveries.\n\nRequires the `posts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "posts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "_def": { "typeName": "ZodDiscriminatedUnion", "discriminator": "action", "options": [ { "_def": { "unknownKeys": "strip", "catchall": { "_def": { "typeName": "ZodNever" }, "~standard": { "version": 1, "vendor": "zod" } }, "typeName": "ZodObject" }, "~standard": { "version": 1, "vendor": "zod" }, "_cached": null }, { "_def": { "unknownKeys": "strip", "catchall": { "_def": { "typeName": "ZodNever" }, "~standard": { "version": 1, "vendor": "zod" } }, "typeName": "ZodObject" }, "~standard": { "version": 1, "vendor": "zod" }, "_cached": null }, { "_def": { "unknownKeys": "strip", "catchall": { "_def": { "typeName": "ZodNever" }, "~standard": { "version": 1, "vendor": "zod" } }, "typeName": "ZodObject" }, "~standard": { "version": 1, "vendor": "zod" }, "_cached": null } ], "optionsMap": {} }, "~standard": { "version": 1, "vendor": "zod" } } } } } } }, "/v1/posts/bulk-import/validate": { "post": { "operationId": "validateBulkImport", "summary": "Validate a bulk-import CSV", "tags": [ "Posts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkImportValidation" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "description": "The file is over the size limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Dry-runs a CSV/TSV import (max 500 data rows, 2 MB) and returns per-row validation results without creating anything. Columns: `content` (required), `schedule_at` (ISO 8601 or `YYYY-MM-DD HH:mm` in the workspace timezone), `accounts` (comma-separated account ids or platform names), `labels`, `media_url`, and per-platform overrides `caption_`.\n\nRequires the `posts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "posts", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "workspace_id": { "type": "string", "format": "uuid" } }, "required": [ "file", "workspace_id" ] } } } } } }, "/v1/posts/bulk-import/commit": { "post": { "operationId": "commitBulkImport", "summary": "Commit a bulk-import CSV", "tags": [ "Posts" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkImportCommitResult" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "description": "The file is over the size limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "422": { "description": "Rows failed validation (`validation_failed`, with the failing `rows`) or the commit was refused (`commit_failed`); nothing was imported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Re-validates the uploaded CSV/TSV and creates one scheduled post per row, all stamped with a fresh batch id. All-or-nothing: if any row fails validation, nothing is created and the failing rows are returned.\n\nRequires the `posts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "posts", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "workspace_id": { "type": "string", "format": "uuid" } }, "required": [ "file", "workspace_id" ] } } } } } }, "/v1/posts/bulk-import/{batchId}": { "delete": { "operationId": "rollbackBulkImport", "summary": "Roll back a bulk-import batch", "tags": [ "Posts" ], "responses": { "200": { "description": "Rolled back", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "integer" } }, "required": [ "deleted" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Soft-deletes the batch's posts that are still draft or scheduled and cancels their queued deliveries. Refused with 409 if any post in the batch has already published or is publishing.\n\nRequires the `posts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "posts", "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Import batch id" } ] } }, "/v1/workspaces": { "get": { "operationId": "listWorkspaces", "summary": "List workspaces", "tags": [ "Workspaces" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceListItem" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Lists every workspace the user belongs to, with connected accounts.\n\nRequires the `workspaces` scope when using an API key.", "x-fopost-scope": "workspaces" }, "post": { "operationId": "createWorkspace", "summary": "Create a workspace", "tags": [ "Workspaces" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `workspaces` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "workspaces", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkspaceRequest" } } } } } }, "/v1/workspaces/{id}": { "get": { "operationId": "getWorkspace", "summary": "Get a workspace", "tags": [ "Workspaces" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceWithAccounts" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `workspaces` scope when using an API key.", "x-fopost-scope": "workspaces", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workspace id" } ] }, "put": { "operationId": "updateWorkspace", "summary": "Update a workspace", "tags": [ "Workspaces" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the workspace owner or admin role.\n\nRequires the `workspaces` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "workspaces", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workspace id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWorkspaceRequest" } } } } }, "delete": { "operationId": "deleteWorkspace", "summary": "Delete a workspace", "tags": [ "Workspaces" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Soft-deletes the workspace. Requires the workspace owner role. Refused with 409 while accounts are still connected, or when it is your only workspace.\n\nRequires the `workspaces` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "workspaces", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workspace id" } ] } }, "/v1/posts/{id}/analytics/collect": { "post": { "operationId": "collectPostAnalytics", "summary": "Refresh one post's metrics now", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectPostResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "description": "Refreshed too often (`too_many_requests`), retry after `retry_after` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Re-reads one post from the network instead of waiting for the next scheduled collection, and stores the reading so it joins that post's timeline. `id` is a FoPost post id or, URL-encoded, the permalink of a post made natively on the network. One post is still a platform call, so this spends the same per-user budget as `POST /v1/analytics/collect`: over the limit, the `429` body carries `retry_after` in seconds. An API key needs the `analytics` scope as well as `posts`.\n\nRequires the `analytics` scope when using an API key.", "x-fopost-scope": "analytics", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "FoPost post id, or a URL-encoded platform permalink" } ] } }, "/v1/workspaces/{id}/analytics": { "get": { "operationId": "getWorkspaceAnalytics", "summary": "Get workspace analytics", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAnalyticsResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Latest follower and post totals for every account in the workspace.\n\nRequires the `workspaces` scope when using an API key.", "x-fopost-scope": "workspaces", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workspace id" } ] } }, "/v1/accounts": { "get": { "operationId": "listAccounts", "summary": "List connected accounts", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AccountSummary" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "external_user_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only accounts connected through a hosted connect link for this end user" }, { "name": "group_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Only accounts in this account group" } ] }, "post": { "operationId": "createAccount", "summary": "Connect an account with credentials", "tags": [ "Accounts" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountCreated" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "A saved card is required past the free account allowance (`card_required`), or a spend cap was reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The workspace already holds an account on this network (`platform_slot_taken`, with `account_id`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "description": "Creates a connected account from caller-supplied credentials (for platforms that use tokens or keys instead of an OAuth redirect flow). Credentials are validated against the platform before the account is stored.\n\nRequires the `accounts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "accounts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountRequest" } } } } } }, "/v1/connect-sessions": { "post": { "operationId": "createConnectSession", "summary": "Create a hosted connect link", "tags": [ "Accounts" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectSession" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Mints a single-use link, open for one hour, that lets one of your end users connect a social account into your workspace with no FoPost login, on a page carrying your `branding`. The account is tagged with `externalUserId`. `redirectUrl` must be on a domain in the workspace redirect allowlist (dashboard → API Keys); the user is sent there with `status`, `platform`, `account_id` and `external_user_id` once connected. `workspaceId` may be omitted for a key bound to one workspace.\n\nRequires the `accounts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "accounts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConnectSessionRequest" } } } } } }, "/v1/connect-sessions/{id}": { "get": { "operationId": "getConnectSession", "summary": "Get a hosted connect link", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectSession" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Poll to learn the outcome: `status` moves from `pending` to `used` and `account_id` is set once the end user has connected. Sessions in other workspaces answer 404.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Connect session id" } ] } }, "/v1/accounts/telegram/connect-code": { "post": { "operationId": "createTelegramConnectCode", "summary": "Create a Telegram connect code", "tags": [ "Accounts" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramConnectCode" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "description": "Mints a one-time code, valid for 15 minutes. Sending `/connect ` to the publishing bot in a private chat, a group, or a channel where the bot is an admin connects that chat to the workspace, with no chat id to paste. `deep_link` and `group_link` carry the code for you. Poll `GET /v1/accounts/telegram/connect-code/status` for the outcome. `workspaceId` may be omitted for a key bound to one workspace.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" } } } } } } } }, "/v1/accounts/telegram/connect-code/status": { "get": { "operationId": "getTelegramConnectStatus", "summary": "Get a Telegram connect code status", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramConnectStatus" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "`status` moves from `pending` to `connected` (with `account_id`) or `failed` (with `reason`), or reads `expired` once the code lapses unused. A code minted by another user answers 404.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "code", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The connect code" } ] } }, "/v1/accounts/{id}/telegram/commands": { "get": { "operationId": "getTelegramBotCommands", "summary": "List Telegram bot commands", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramBotCommands" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "The network rejected the request (`platform_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "The command menu the bot shows in this chat. Commands are scoped to the connected chat; channels, and chats not connected with a code, answer 400.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" } ] }, "put": { "operationId": "setTelegramBotCommands", "summary": "Set Telegram bot commands", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramBotCommands" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "The network rejected the request (`platform_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Replaces the command menu for this chat. Up to 100 commands, each 1-32 lowercase letters, digits or underscores with a 1-256 character description.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetTelegramBotCommandsRequest" } } } } }, "delete": { "operationId": "deleteTelegramBotCommands", "summary": "Clear Telegram bot commands", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramBotCommands" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "The network rejected the request (`platform_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" } ] } }, "/v1/accounts/{id}/messaging/ice-breakers": { "get": { "operationId": "getIceBreakers", "summary": "Get ice breakers", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaIceBreakers" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "The network rejected the request (`platform_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "The tappable prompts a new Messenger or Instagram conversation opens with. Up to four; networks without them answer 400.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" } ] }, "put": { "operationId": "setIceBreakers", "summary": "Set ice breakers", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaIceBreakers" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "The network rejected the request (`platform_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Replaces the ice breakers for this account. Up to four, each an 80-character question with a payload your webhook receives.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetIceBreakersRequest" } } } } }, "delete": { "operationId": "deleteIceBreakers", "summary": "Clear ice breakers", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaIceBreakers" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "The network rejected the request (`platform_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" } ] } }, "/v1/accounts/{id}/messaging/persistent-menu": { "get": { "operationId": "getPersistentMenu", "summary": "Get the persistent menu", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaPersistentMenu" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "The network rejected the request (`platform_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "The always-visible Messenger menu. Facebook Pages only; other networks answer 400.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" } ] }, "put": { "operationId": "setPersistentMenu", "summary": "Set the persistent menu", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaPersistentMenu" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "The network rejected the request (`platform_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Replaces the menu, one entry per locale. Up to three items each, either a postback or an http(s) link.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPersistentMenuRequest" } } } } }, "delete": { "operationId": "deletePersistentMenu", "summary": "Clear the persistent menu", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaPersistentMenu" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "The network rejected the request (`platform_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" } ] } }, "/v1/accounts/{id}/messaging/greeting": { "get": { "operationId": "getGreeting", "summary": "Get the greeting", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaGreeting" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "The network rejected the request (`platform_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "The text shown before a Messenger conversation starts. Facebook Pages only; other networks answer 400.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" } ] }, "put": { "operationId": "setGreeting", "summary": "Set the greeting", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaGreeting" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "The network rejected the request (`platform_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Replaces the greeting, one entry per locale, each up to 160 characters.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetGreetingRequest" } } } } }, "delete": { "operationId": "deleteGreeting", "summary": "Clear the greeting", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaGreeting" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "The network rejected the request (`platform_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" } ] } }, "/v1/accounts/{id}/webhook-subscription": { "get": { "operationId": "getWebhookSubscription", "summary": "Get the webhook subscription", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscription" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "The network rejected the request (`platform_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "What the network currently delivers to our webhook for this account. `subscribed` is false when the subscription lapsed or a required field is missing.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" } ] }, "post": { "operationId": "resubscribeWebhook", "summary": "Re-subscribe the webhook", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscription" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "The network rejected the request (`platform_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Subscribes the app to every field this account needs, lapsed or not.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" } ] } }, "/v1/accounts/health": { "get": { "operationId": "getAccountsHealthSummary", "summary": "Get health summary for all accounts", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountsHealthSummaryResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] } }, "/v1/accounts/{id}": { "get": { "operationId": "getAccount", "summary": "Get an account", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDetail" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" } ] }, "patch": { "operationId": "updateAccount", "summary": "Rename an account", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "platform_name": { "type": "string" } }, "required": [ "id", "name", "platform_name" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Sets a display name shown instead of the platform name. `null` or an empty string restores the platform name.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAccountRequest" } } } } }, "delete": { "operationId": "deleteAccount", "summary": "Disconnect an account", "tags": [ "Accounts" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Revokes platform access where supported, clears stored credentials, and soft-deletes the account.\n\nRequires the `accounts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" } ] } }, "/v1/accounts/{id}/move": { "post": { "operationId": "moveAccount", "summary": "Move an account to another workspace", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" } }, "required": [ "id", "workspace_id" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Moves the account, its connection and its inbox and analytics history to another workspace in one step. The caller must own both workspaces; any other target answers 404. The move is refused with 409 `move_blocked` and the `blocking_tables` list when the account still has records that belong to its current workspace (posts, automations, ads and similar), or with 409 when the target already has an account on that network. The account leaves its account groups.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveAccountRequest" } } } } } }, "/v1/account-groups": { "get": { "operationId": "listAccountGroups", "summary": "List account groups", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AccountGroup" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] }, "post": { "operationId": "createAccountGroup", "summary": "Create an account group", "tags": [ "Accounts" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountGroup" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountGroupRequest" } } } } } }, "/v1/account-groups/{id}": { "get": { "operationId": "getAccountGroup", "summary": "Get an account group", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountGroup" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account group id" } ] }, "patch": { "operationId": "updateAccountGroup", "summary": "Rename an account group", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountGroup" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account group id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAccountGroupRequest" } } } } }, "delete": { "operationId": "deleteAccountGroup", "summary": "Delete an account group", "tags": [ "Accounts" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Deletes the group only; its accounts stay connected.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account group id" } ] } }, "/v1/account-groups/{id}/members": { "put": { "operationId": "setAccountGroupMembers", "summary": "Replace an account group's members", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountGroup" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account group id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetAccountGroupMembersRequest" } } } } } }, "/v1/accounts/{id}/primary": { "post": { "operationId": "toggleAccountPrimary", "summary": "Toggle primary flag", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "is_primary": { "type": "boolean" } }, "required": [ "id", "is_primary" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `accounts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" } ] } }, "/v1/accounts/{id}/validate": { "post": { "operationId": "validateAccountCredentials", "summary": "Validate account credentials", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "valid": { "type": "boolean" }, "health_status": { "type": "string", "enum": [ "healthy", "expired" ] }, "username": { "type": "string" }, "name": { "type": "string" }, "avatar": { "type": [ "string", "null" ] }, "delivery": { "type": "string", "enum": [ "extension" ], "description": "Set for manual platforms, which publish through the browser extension" }, "message": { "type": "string", "description": "Set for manual platforms: how delivery works for this network" } }, "required": [ "account_id", "platform", "valid", "health_status" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Checks the stored credentials against the platform and updates the health status.\n\nRequires the `accounts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" } ] } }, "/v1/accounts/{id}/health": { "get": { "operationId": "getAccountHealth", "summary": "Get account health", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountHealth" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" }, { "name": "refresh", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Pass `true` to run a fresh health check" } ] } }, "/v1/accounts/{id}/refresh-token": { "post": { "operationId": "refreshAccountToken", "summary": "Refresh an OAuth token", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "expires_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "expires_at" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Platform does not support token refresh, or the refresh failed (`token_refresh_failed`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Manually refreshes the OAuth token for platforms that support it.\n\nRequires the `accounts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" } ] } }, "/v1/accounts/{id}/pinterest/boards": { "get": { "operationId": "listPinterestBoards", "summary": "List Pinterest boards", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PinterestBoard" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Pinterest did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Boards this connection can pin to, for the composer board picker.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Pinterest account id" } ] }, "post": { "operationId": "createPinterestBoard", "summary": "Create a Pinterest board", "tags": [ "Accounts" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PinterestBoard" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Pinterest did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Creates a board on the connected account. Pass its id as the `board_id` platform setting to pin to it.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Pinterest account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePinterestBoardRequest" } } } } } }, "/v1/accounts/{id}/youtube/playlists": { "get": { "operationId": "listYouTubePlaylists", "summary": "List YouTube playlists", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/YouTubePlaylist" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "YouTube did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "The connected channel's own playlists, with the stored default marked.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "YouTube account id" } ] }, "post": { "operationId": "createYouTubePlaylist", "summary": "Create a YouTube playlist", "tags": [ "Accounts" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/YouTubePlaylist" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "YouTube did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "YouTube account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateYouTubePlaylistRequest" } } } } } }, "/v1/accounts/{id}/youtube/playlists/default": { "put": { "operationId": "setDefaultYouTubePlaylist", "summary": "Set the default YouTube playlist", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "playlist_id": { "type": [ "string", "null" ] } }, "required": [ "playlist_id" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "The playlist a new video joins when the post does not pick one. Stored on the connection, not on YouTube; `null` clears it.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "YouTube account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDefaultYouTubePlaylistRequest" } } } } } }, "/v1/accounts/{id}/youtube/videos/{videoId}/captions": { "get": { "operationId": "listYouTubeCaptions", "summary": "List caption tracks", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/YouTubeCaptionTrack" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "YouTube did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Caption tracks on one of the channel's own videos.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "YouTube account id" }, { "name": "videoId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "YouTube video id" } ] }, "post": { "operationId": "uploadYouTubeCaptions", "summary": "Upload a caption track", "tags": [ "Accounts" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/YouTubeCaptionTrack" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "YouTube did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Uploads a subtitle file. YouTube reads SRT and WebVTT and sniffs which one it is, so the format is not declared.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "YouTube account id" }, { "name": "videoId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "YouTube video id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadYouTubeCaptionsRequest" } } } } } }, "/v1/accounts/{id}/youtube/captions/{captionId}": { "get": { "operationId": "readYouTubeTranscript", "summary": "Read a transcript", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/YouTubeTranscript" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "YouTube did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "The text of one caption track.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "YouTube account id" }, { "name": "captionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Caption track id" } ] } }, "/v1/accounts/{id}/bluesky/languages": { "get": { "operationId": "getBlueskyLanguages", "summary": "Read the default post languages", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlueskyLanguages" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "What a post from this connection is written in when the post does not say. Bluesky filters the feed by language.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Bluesky account id" } ] }, "put": { "operationId": "setBlueskyLanguages", "summary": "Set the default post languages", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlueskyLanguages" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "BCP-47 tags, at most three. An empty list clears the default.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Bluesky account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetBlueskyLanguagesRequest" } } } } } }, "/v1/accounts/{id}/tiktok/creator-info": { "get": { "operationId": "getTikTokCreatorInfo", "summary": "Read TikTok creator info", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TikTokCreatorInfo" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "TikTok has not granted the product or scope this needs (`platform_permission`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "TikTok did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "The account-level switches TikTok enforces at publish time: which privacy levels are open, whether comments, Duet or Stitch are off, and the creator's own video length cap. These are changed in the TikTok app.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "TikTok account id" } ] } }, "/v1/accounts/{id}/instagram/audio": { "get": { "operationId": "searchInstagramAudio", "summary": "Search Instagram's audio library", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InstagramAudio" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Instagram did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Tracks a Reel can carry. With no query Instagram answers with what is trending. Attach one by sending its id as the `audio_id` platform setting.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Instagram account id" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Keyword; omit for trending" }, { "name": "audio_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "music", "original_sound" ] } } ] } }, "/v1/accounts/{id}/instagram/publishing-limit": { "get": { "operationId": "getInstagramPublishingLimit", "summary": "Read the publishing limit", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstagramPublishingLimit" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Instagram did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "How many posts this account has published in the rolling window, and how many are left before Instagram refuses the next one.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Instagram account id" } ] } }, "/v1/accounts/{id}/instagram/stories": { "get": { "operationId": "listInstagramStories", "summary": "List active stories", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InstagramStory" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Instagram did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Stories still inside their 24 hours, whether or not they were posted through FoPost. Story media is not on the media edge.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Instagram account id" }, { "name": "insights", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Fetch each story's insights; one extra call per story" } ] } }, "/v1/accounts/{id}/instagram/stories/{storyId}/insights": { "get": { "operationId": "getInstagramStoryInsights", "summary": "Read story insights", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstagramStoryInsights" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Instagram did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Views, reach, replies and navigation for one story. Instagram withholds these for a story too young or too small to report, and answers empty.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Instagram account id" }, { "name": "storyId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Story media id" } ] } }, "/v1/accounts/{id}/linkedin/mentions": { "get": { "operationId": "searchLinkedInMentions", "summary": "Find a LinkedIn mention", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedInMention" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "LinkedIn did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Organizations a post can mention, with the URN that makes the text render as a link. People are not searchable: LinkedIn has no public person search, so a member mention needs a URN you already hold.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "LinkedIn account id" }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Name or vanity name" } ] } }, "/v1/accounts/{id}/tiktok/music": { "get": { "operationId": "searchTikTokMusic", "summary": "Search TikTok's Commercial Music Library", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TikTokMusic" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "TikTok has not granted the product or scope this needs (`platform_permission`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "TikTok did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Tracks a post may use. Needs the Marketing API product on the TikTok app; without it the request answers 403 rather than an empty list.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "TikTok account id" }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search term" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "1 to 50, default 20" } ] } }, "/v1/accounts/{id}/tiktok/locations": { "get": { "operationId": "searchTikTokLocations", "summary": "Search TikTok places", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TikTokPlace" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "TikTok has not granted the product or scope this needs (`platform_permission`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "TikTok did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Places a post can be tagged with. Same Marketing API product as the music library.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "TikTok account id" }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search term" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "1 to 50, default 20" } ] } }, "/v1/accounts/{id}/tiktok/video-download": { "post": { "operationId": "lookupTikTokVideo", "summary": "Resolve a TikTok video for repurposing", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TikTokVideoSource" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "TikTok has not granted the product or scope this needs (`platform_permission`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "TikTok did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Resolves a share link to one of the connected account's own videos and hands back the address a repurpose run reads. A link to someone else's video answers 404.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "TikTok account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TikTokVideoLookupRequest" } } } } } }, "/v1/accounts/{id}/slack/channels": { "get": { "operationId": "listSlackChannels", "summary": "List Slack channels", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SlackChannel" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account posts through a webhook (`webhook_connection`); reconnect with the Slack app", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Slack did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Channels the Slack app can post to in the connected workspace: every public channel, and private ones the app was invited to.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Slack account id" } ] } }, "/v1/accounts/{id}/slack/members": { "get": { "operationId": "listSlackMembers", "summary": "List Slack members", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SlackMember" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account posts through a webhook (`webhook_connection`); reconnect with the Slack app", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Slack did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "People in the connected Slack workspace, for addressing a DM.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Slack account id" } ] } }, "/v1/accounts/{id}/slack/identity": { "get": { "operationId": "getSlackIdentity", "summary": "Get the Slack posting identity", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlackIdentity" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account posts through a webhook (`webhook_connection`); reconnect with the Slack app", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Slack account id" } ] }, "patch": { "operationId": "updateSlackIdentity", "summary": "Set the Slack posting identity", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlackIdentity" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account posts through a webhook (`webhook_connection`); reconnect with the Slack app", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "The name and icon the account posts under. Omitted fields keep their value and `null` clears one. Set `icon_url` or `icon_emoji`, not both; setting one clears the other.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Slack account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlackIdentityRequest" } } } } } }, "/v1/accounts/{id}/discord/channels": { "get": { "operationId": "listDiscordChannels", "summary": "List Discord channels", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DiscordChannel" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account posts through a webhook (`webhook_connection`); upgrade it to the bot first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Discord did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Text channels the bot can post to in the connected server.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Discord account id" } ] } }, "/v1/accounts/{id}/discord/channels/current": { "patch": { "operationId": "switchDiscordChannel", "summary": "Move the account to another channel", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "is_current": { "type": "boolean", "const": true } }, "required": [ "id", "name", "is_current" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account posts through a webhook (`webhook_connection`), or the bot cannot post in the chosen channel (`channel_not_writable`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Discord did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "The channel must be one the bot can post to in the same server.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Discord account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscordChannelSwitchRequest" } } } } } }, "/v1/accounts/{id}/discord/identity": { "get": { "operationId": "getDiscordIdentity", "summary": "Get the Discord posting identity", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscordIdentity" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account posts through a webhook (`webhook_connection`); upgrade it to the bot first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Discord account id" } ] }, "patch": { "operationId": "updateDiscordIdentity", "summary": "Set the Discord posting identity", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscordIdentity" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account posts through a webhook (`webhook_connection`); upgrade it to the bot first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Discord did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "The nickname and avatar the bot wears in this server. Omitted fields keep their value and `null` clears one.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Discord account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscordIdentityRequest" } } } } } }, "/v1/accounts/{id}/discord/messages/pinned": { "get": { "operationId": "listDiscordPins", "summary": "List pinned messages", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DiscordMessage" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account posts through a webhook (`webhook_connection`); upgrade it to the bot first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Discord did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Discord account id" } ] } }, "/v1/accounts/{id}/discord/messages/{messageId}": { "delete": { "operationId": "deleteDiscordMessage", "summary": "Delete a message", "tags": [ "Accounts" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account posts through a webhook (`webhook_connection`); upgrade it to the bot first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Discord did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Discord account id" }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Discord message id" } ] } }, "/v1/accounts/{id}/discord/messages/{messageId}/pin": { "post": { "operationId": "pinDiscordMessage", "summary": "Pin a message", "tags": [ "Accounts" ], "responses": { "204": { "description": "Pinned", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account posts through a webhook (`webhook_connection`); upgrade it to the bot first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Discord did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Discord account id" }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Discord message id" } ] }, "delete": { "operationId": "unpinDiscordMessage", "summary": "Unpin a message", "tags": [ "Accounts" ], "responses": { "204": { "description": "Unpinned", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account posts through a webhook (`webhook_connection`); upgrade it to the bot first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Discord did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Discord account id" }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Discord message id" } ] } }, "/v1/accounts/{id}/discord/messages/{messageId}/crosspost": { "post": { "operationId": "crosspostDiscordMessage", "summary": "Publish a message to following servers", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "channel_id": { "type": "string" } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account posts through a webhook (`webhook_connection`); upgrade it to the bot first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Discord did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Only a message in an announcement channel can be crossposted.\n\nRequires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Discord account id" }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Discord message id" } ] } }, "/v1/accounts/{id}/discord/messages/{messageId}/thread": { "post": { "operationId": "createDiscordThread", "summary": "Start a thread on a message", "tags": [ "Accounts" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "parent_id": { "type": [ "string", "null" ] } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account posts through a webhook (`webhook_connection`); upgrade it to the bot first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Discord did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Discord account id" }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Discord message id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscordThreadRequest" } } } } } }, "/v1/accounts/{id}/discord/events": { "get": { "operationId": "listDiscordEvents", "summary": "List scheduled events", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DiscordScheduledEvent" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account posts through a webhook (`webhook_connection`); upgrade it to the bot first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Discord did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Discord account id" } ] }, "post": { "operationId": "createDiscordEvent", "summary": "Create a scheduled event", "tags": [ "Accounts" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscordScheduledEvent" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account posts through a webhook (`webhook_connection`); upgrade it to the bot first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Discord did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Give a `channel_id` for an event in a voice or stage channel, or a `location` and an `end_time` for one somewhere else.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Discord account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscordScheduledEventRequest" } } } } } }, "/v1/accounts/{id}/discord/events/{eventId}": { "get": { "operationId": "getDiscordEvent", "summary": "Get a scheduled event", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscordScheduledEvent" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account posts through a webhook (`webhook_connection`); upgrade it to the bot first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Discord did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Discord account id" }, { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Discord event id" } ] }, "patch": { "operationId": "updateDiscordEvent", "summary": "Update a scheduled event", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscordScheduledEvent" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account posts through a webhook (`webhook_connection`); upgrade it to the bot first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Discord did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Discord account id" }, { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Discord event id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscordScheduledEventPatchRequest" } } } } }, "delete": { "operationId": "deleteDiscordEvent", "summary": "Delete a scheduled event", "tags": [ "Accounts" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account posts through a webhook (`webhook_connection`); upgrade it to the bot first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Discord did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Discord account id" }, { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Discord event id" } ] } }, "/v1/accounts/{id}/discord/members": { "get": { "operationId": "listDiscordMembers", "summary": "List or search server members", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DiscordMember" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account posts through a webhook (`webhook_connection`); upgrade it to the bot first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Discord did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Discord account id" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search by username or nickname prefix" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "maximum": 1000 } } ] } }, "/v1/accounts/{id}/discord/members/{memberId}": { "get": { "operationId": "getDiscordMember", "summary": "Get a server member", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscordMember" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account posts through a webhook (`webhook_connection`); upgrade it to the bot first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Discord did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Discord account id" }, { "name": "memberId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Discord user id" } ] } }, "/v1/accounts/{id}/discord/roles": { "get": { "operationId": "listDiscordRoles", "summary": "List server roles", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DiscordRole" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account posts through a webhook (`webhook_connection`); upgrade it to the bot first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Discord did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Discord account id" } ] }, "post": { "operationId": "createDiscordRole", "summary": "Create a role", "tags": [ "Accounts" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscordRole" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account posts through a webhook (`webhook_connection`); upgrade it to the bot first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Discord did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Discord account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscordRoleRequest" } } } } } }, "/v1/accounts/{id}/discord/roles/{roleId}": { "patch": { "operationId": "updateDiscordRole", "summary": "Update a role", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscordRole" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account posts through a webhook (`webhook_connection`); upgrade it to the bot first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Discord did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Discord account id" }, { "name": "roleId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Discord role id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscordRolePatchRequest" } } } } }, "delete": { "operationId": "deleteDiscordRole", "summary": "Delete a role", "tags": [ "Accounts" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account posts through a webhook (`webhook_connection`); upgrade it to the bot first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Discord did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Discord account id" }, { "name": "roleId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Discord role id" } ] } }, "/v1/accounts/{id}/discord/roles/{roleId}/members/{memberId}": { "put": { "operationId": "addDiscordMemberRole", "summary": "Give a member a role", "tags": [ "Accounts" ], "responses": { "204": { "description": "Assigned", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account posts through a webhook (`webhook_connection`); upgrade it to the bot first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Discord did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Discord account id" }, { "name": "roleId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Discord role id" }, { "name": "memberId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Discord user id" } ] }, "delete": { "operationId": "removeDiscordMemberRole", "summary": "Take a role from a member", "tags": [ "Accounts" ], "responses": { "204": { "description": "Removed", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account posts through a webhook (`webhook_connection`); upgrade it to the bot first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Discord did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Discord account id" }, { "name": "roleId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Discord role id" }, { "name": "memberId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Discord user id" } ] } }, "/v1/accounts/{id}/discord/dm": { "post": { "operationId": "sendDiscordDm", "summary": "Send a direct message to a member", "tags": [ "Accounts" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "channel_id": { "type": "string" } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account posts through a webhook (`webhook_connection`); upgrade it to the bot first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Discord did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Discord account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscordDmRequest" } } } } } }, "/v1/accounts/{id}/gbp/location": { "get": { "operationId": "getGoogleBusinessLocation", "summary": "Get the Business Profile location", "tags": [ "Google Business" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Business Profile management is not available (`not_configured`): Google has not granted this deployment API access yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "The location behind a connected Google Business account, in the Business Information API shape.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Google Business account id" } ] }, "patch": { "operationId": "updateGoogleBusinessLocation", "summary": "Update the Business Profile location", "tags": [ "Google Business" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Business Profile management is not available (`not_configured`): Google has not granted this deployment API access yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Only the fields present in the body change; omitted fields are left alone.\n\nRequires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Google Business account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleBusinessLocationRequest" } } } } } }, "/v1/accounts/{id}/gbp/attributes": { "get": { "operationId": "getGoogleBusinessAttributes", "summary": "Get Business Profile attributes", "tags": [ "Google Business" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Business Profile management is not available (`not_configured`): Google has not granted this deployment API access yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "The attribute values set on the location. Pass `available=true` to list the attributes Google offers for its category and region instead.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Google Business account id" }, { "name": "available", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "category_name", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "region_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "language_code", "in": "query", "required": false, "schema": { "type": "string" } } ] }, "patch": { "operationId": "updateGoogleBusinessAttributes", "summary": "Update Business Profile attributes", "tags": [ "Google Business" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Business Profile management is not available (`not_configured`): Google has not granted this deployment API access yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Only the named attributes change; every other attribute is left alone.\n\nRequires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Google Business account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleBusinessAttributesRequest" } } } } } }, "/v1/accounts/{id}/gbp/menus": { "get": { "operationId": "getGoogleBusinessMenus", "summary": "Get the food menus", "tags": [ "Google Business" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Business Profile management is not available (`not_configured`): Google has not granted this deployment API access yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Google Business account id" } ] }, "put": { "operationId": "replaceGoogleBusinessMenus", "summary": "Replace the food menus", "tags": [ "Google Business" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Business Profile management is not available (`not_configured`): Google has not granted this deployment API access yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Google has no per-section patch, so the whole menu set is replaced.\n\nRequires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Google Business account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleBusinessMenusRequest" } } } } } }, "/v1/accounts/{id}/gbp/services": { "get": { "operationId": "getGoogleBusinessServices", "summary": "Get the service list", "tags": [ "Google Business" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Business Profile management is not available (`not_configured`): Google has not granted this deployment API access yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Google Business account id" } ] }, "put": { "operationId": "replaceGoogleBusinessServices", "summary": "Replace the service list", "tags": [ "Google Business" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Business Profile management is not available (`not_configured`): Google has not granted this deployment API access yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Google Business account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleBusinessServicesRequest" } } } } } }, "/v1/accounts/{id}/gbp/media": { "get": { "operationId": "listGoogleBusinessMedia", "summary": "List location photos", "tags": [ "Google Business" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Business Profile management is not available (`not_configured`): Google has not granted this deployment API access yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Google Business account id" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "page_token", "in": "query", "required": false, "schema": { "type": "string" } } ] }, "post": { "operationId": "addGoogleBusinessMedia", "summary": "Add a location photo", "tags": [ "Google Business" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Business Profile management is not available (`not_configured`): Google has not granted this deployment API access yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "The photo is a media-library asset in the same workspace, handed to Google as a short-lived signed URL. JPEG and PNG only.\n\nRequires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Google Business account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleBusinessMediaRequest" } } } } } }, "/v1/accounts/{id}/gbp/media/{mediaKey}": { "delete": { "operationId": "deleteGoogleBusinessMedia", "summary": "Remove a location photo", "tags": [ "Google Business" ], "responses": { "204": { "description": "Removed", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Business Profile management is not available (`not_configured`): Google has not granted this deployment API access yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Google Business account id" }, { "name": "mediaKey", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Google media key" } ] } }, "/v1/accounts/{id}/gbp/place-actions": { "get": { "operationId": "listGoogleBusinessPlaceActions", "summary": "List place action links", "tags": [ "Google Business" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Business Profile management is not available (`not_configured`): Google has not granted this deployment API access yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "The Book, Order and Reserve buttons shown on the profile.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Google Business account id" } ] }, "post": { "operationId": "createGoogleBusinessPlaceAction", "summary": "Add a place action link", "tags": [ "Google Business" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Business Profile management is not available (`not_configured`): Google has not granted this deployment API access yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Google Business account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleBusinessPlaceActionRequest" } } } } } }, "/v1/accounts/{id}/gbp/place-actions/{linkId}": { "patch": { "operationId": "updateGoogleBusinessPlaceAction", "summary": "Update a place action link", "tags": [ "Google Business" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Business Profile management is not available (`not_configured`): Google has not granted this deployment API access yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Google Business account id" }, { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Place action link id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleBusinessPlaceActionPatchRequest" } } } } }, "delete": { "operationId": "deleteGoogleBusinessPlaceAction", "summary": "Remove a place action link", "tags": [ "Google Business" ], "responses": { "204": { "description": "Removed", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Business Profile management is not available (`not_configured`): Google has not granted this deployment API access yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Google Business account id" }, { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Place action link id" } ] } }, "/v1/accounts/{id}/gbp/verification": { "get": { "operationId": "getGoogleBusinessVerificationOptions", "summary": "List verification options", "tags": [ "Google Business" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Business Profile management is not available (`not_configured`): Google has not granted this deployment API access yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "The ways Google will let this location be verified.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Google Business account id" }, { "name": "language_code", "in": "query", "required": false, "schema": { "type": "string", "default": "en" } } ] } }, "/v1/accounts/{id}/gbp/verification/start": { "post": { "operationId": "startGoogleBusinessVerification", "summary": "Start verification", "tags": [ "Google Business" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Business Profile management is not available (`not_configured`): Google has not granted this deployment API access yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "The response names the pending verification to complete with the PIN.\n\nRequires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Google Business account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleBusinessVerifyRequest" } } } } } }, "/v1/accounts/{id}/gbp/verification/complete": { "post": { "operationId": "completeGoogleBusinessVerification", "summary": "Complete verification", "tags": [ "Google Business" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Business Profile management is not available (`not_configured`): Google has not granted this deployment API access yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Google Business account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleBusinessVerifyCompleteRequest" } } } } } }, "/v1/accounts/{id}/gbp/performance": { "get": { "operationId": "getGoogleBusinessPerformance", "summary": "Get Business Profile performance", "tags": [ "Google Business" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Business Profile management is not available (`not_configured`): Google has not granted this deployment API access yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Daily impressions, calls, direction requests and website clicks for the date range. Pass `keywords=true` for the monthly search terms instead.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Google Business account id" }, { "name": "start_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "daily_metrics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "BUSINESS_IMPRESSIONS_DESKTOP_MAPS", "BUSINESS_IMPRESSIONS_DESKTOP_SEARCH", "BUSINESS_IMPRESSIONS_MOBILE_MAPS", "BUSINESS_IMPRESSIONS_MOBILE_SEARCH", "BUSINESS_CONVERSATIONS", "BUSINESS_DIRECTION_REQUESTS", "CALL_CLICKS", "WEBSITE_CLICKS", "BUSINESS_BOOKINGS", "BUSINESS_FOOD_ORDERS", "BUSINESS_FOOD_MENU_CLICKS" ] } }, "description": "Repeat the parameter for each metric, or send one comma-separated value. Defaults to the common set." }, { "name": "keywords", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/v1/accounts/{id}/gbp/assign": { "post": { "operationId": "assignGoogleBusinessLocation", "summary": "Assign the location to another workspace", "tags": [ "Google Business" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" } }, "required": [ "id", "workspace_id" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Business Profile management is not available (`not_configured`): Google has not granted this deployment API access yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Moves the connection and every row keyed to it in one transaction. The caller must own both workspaces.\n\nRequires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Google Business account id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveAccountRequest" } } } } } }, "/v1/accounts/{id}/insights": { "get": { "operationId": "getAccountPlatformMetrics", "summary": "Get an account’s per-network metric set", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountPlatformMetricsResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "This network’s metric access has not been granted yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Pass `raw=true` for the numbers only this network reports, keyed by the platform’s own metric names — ad-break earnings, story taps, a retention curve, the search terms behind a listing. Read from the newest collected snapshot, never fetched live.\n\nA network whose metric access has been requested but not granted answers `503 platform_metrics_unavailable` rather than an empty set.\n\nRequires the `analytics` scope when using an API key.", "x-fopost-scope": "analytics", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" }, { "name": "raw", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "true" ] }, "description": "Pass `true` for the per-network metric set" } ] } }, "/v1/accounts/{id}/native-posts": { "get": { "operationId": "listAccountNativePosts", "summary": "List posts made outside FoPost", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativePostListResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Posts that exist on the account but never went out through FoPost, newest first, with the freshest metrics held for each. An API key needs the `analytics` scope as well as `accounts`.\n\nRequires the `analytics` scope when using an API key.", "x-fopost-scope": "analytics", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 365 }, "description": "Only posts published in the last this many days" } ] } }, "/v1/accounts/{id}/analytics": { "get": { "operationId": "getAccountAnalyticsHistory", "summary": "Get account analytics history", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountAnalyticsHistoryResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Account-level snapshots (followers, reach, profile views), newest first.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 30, "maximum": 100 } } ] } }, "/v1/accounts/{accountId}/communities": { "get": { "operationId": "listCommunities", "summary": "List X communities for an account", "tags": [ "Communities" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Community" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Only X (Twitter) accounts have communities.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id (must be an X account)" } ] } }, "/v1/accounts/{accountId}/communities/sync": { "post": { "operationId": "syncCommunities", "summary": "Sync communities from X", "tags": [ "Communities" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Community" } }, "note": { "type": "string" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Fetches the account’s communities from X. Falls back to the stored list (with an explanatory `note`) when the X API is unavailable.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id (must be an X account)" } ] } }, "/v1/accounts/{accountId}/communities/search": { "get": { "operationId": "searchCommunities", "summary": "Search X communities", "tags": [ "Communities" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "member_count": { "type": "integer" } } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "The X API rejected or failed the search (`platform_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id (must be an X account)" }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search keyword" } ] } }, "/v1/accounts/{accountId}/communities/manual": { "post": { "operationId": "addCommunityManually", "summary": "Add a community by id", "tags": [ "Communities" ], "responses": { "200": { "description": "Community was already linked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Community" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Community" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Returns the existing record (200) if the community is already linked.\n\nRequires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id (must be an X account)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddCommunityRequest" } } } } } }, "/v1/accounts/{accountId}/communities/{communityId}": { "delete": { "operationId": "removeCommunity", "summary": "Remove a community", "tags": [ "Communities" ], "responses": { "204": { "description": "Removed", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `accounts` scope when using an API key.", "x-fopost-scope": "accounts", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" }, { "name": "communityId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Internal community id (from the list response)" } ] } }, "/v1/labels": { "get": { "operationId": "listLabels", "summary": "List labels", "tags": [ "Labels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LabelListItem" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `labels` scope when using an API key.", "x-fopost-scope": "labels", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] }, "post": { "operationId": "createLabel", "summary": "Create a label", "tags": [ "Labels" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Label" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `labels` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "labels", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLabelRequest" } } } } } }, "/v1/labels/{id}": { "get": { "operationId": "getLabel", "summary": "Get a label", "tags": [ "Labels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Label" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `labels` scope when using an API key.", "x-fopost-scope": "labels", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Label id" } ] }, "put": { "operationId": "updateLabel", "summary": "Update a label", "tags": [ "Labels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Label" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `labels` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "labels", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Label id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLabelRequest" } } } } }, "delete": { "operationId": "deleteLabel", "summary": "Delete a label", "tags": [ "Labels" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `labels` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "labels", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Label id" } ] } }, "/v1/logs": { "get": { "operationId": "listLogs", "summary": "List request logs", "tags": [ "Workspaces" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestLogListResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Recent API activity, newest first: every request members made against the workspace, with route, status code, duration and any error message. Omit workspace_id to read every workspace the caller belongs to plus their own account-level requests. `summary` carries totals and hourly buckets for the whole filtered window. Rows are kept for 30 days.\n\nRequires the `workspaces` scope when using an API key.", "x-fopost-scope": "workspaces", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 7, "minimum": 1, "maximum": 30 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "success", "failed" ] } }, { "name": "method", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status_code", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "route", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exact route pattern, e.g. /v1/posts/{id}" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Substring match against path and message" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Cursor: `meta.next_cursor` from the previous page (rows older than this id)" } ] } }, "/v1/activity": { "get": { "operationId": "listActivity", "summary": "List activity", "tags": [ "Workspaces" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityListResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "What happened in a workspace, newest first: publishes, account connections and health changes, webhook deliveries, inbox replies, automation runs and billing. Rows are kept for 90 days. Omit workspace_id to read every workspace the caller belongs to. `kind=security` is the audit log — members joining, leaving, changing role or access, and changes to two-step verification, passkeys, single sign-on and signed-in devices. Security rows are append-only and never pruned.\n\nRequires the `analytics` scope when using an API key.", "x-fopost-scope": "analytics", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "publish", "connection", "webhook", "inbox", "automation", "billing", "security" ] } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only events at or after this time" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only events at or before this time" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "next_cursor from the previous page" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } } ] } }, "/v1/webhooks": { "get": { "operationId": "listWebhooks", "summary": "List webhooks", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `webhooks` scope when using an API key.", "x-fopost-scope": "webhooks" }, "post": { "operationId": "createWebhook", "summary": "Create a webhook", "tags": [ "Webhooks" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreated" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Registers an HTTPS endpoint for workspace events. The signing `secret` is returned only in this response — store it to verify payloads.\n\nRequires the `webhooks` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "webhooks", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } } } } }, "/v1/webhooks/{id}": { "put": { "operationId": "updateWebhook", "summary": "Update a webhook", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpdated" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Re-enabling a webhook (`active: true`) resets its failure count.\n\nRequires the `webhooks` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "webhooks", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Webhook id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" } } } } }, "delete": { "operationId": "deleteWebhook", "summary": "Delete a webhook", "tags": [ "Webhooks" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `webhooks` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "webhooks", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Webhook id" } ] } }, "/v1/webhooks/{id}/test": { "post": { "operationId": "testWebhook", "summary": "Send a test event", "tags": [ "Webhooks" ], "responses": { "204": { "description": "Test dispatched", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Dispatches a test `post.published` payload to this endpoint only, whatever it subscribes to.\n\nRequires the `webhooks` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "webhooks", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Webhook id" } ] } }, "/v1/webhooks/{id}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "summary": "List deliveries", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Every delivery attempt to this webhook, newest first, with the response it got. Attempts are kept for 30 days.\n\nRequires the `webhooks` scope when using an API key.", "x-fopost-scope": "webhooks", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Webhook id" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "success", "failed" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 } } ] } }, "/v1/webhooks/{id}/deliveries/{deliveryId}": { "get": { "operationId": "getWebhookDelivery", "summary": "Get a delivery", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryDetail" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "One attempt, including the payload that was sent.\n\nRequires the `webhooks` scope when using an API key.", "x-fopost-scope": "webhooks", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Webhook id" }, { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Delivery id" } ] } }, "/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver": { "post": { "operationId": "redeliverWebhookDelivery", "summary": "Redeliver", "tags": [ "Webhooks" ], "responses": { "204": { "description": "Redelivery queued", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Sends the delivery again with the identical body, so `X-FoPost-Signature` and `X-FoPost-Delivery` match the original; only the timestamp and `X-FoPost-Signature-256` are fresh. One attempt, logged as the next attempt of that delivery. A paused webhook answers 409.\n\nRequires the `webhooks` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "webhooks", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Webhook id" }, { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Delivery id" } ] } }, "/v1/analytics/overview": { "get": { "operationId": "getAnalyticsOverview", "summary": "Get analytics overview", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsOverviewResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Cross-workspace dashboard totals, period deltas, today’s stats, and a per-account breakdown with follower history.\n\nRequires the `analytics` scope when using an API key.", "x-fopost-scope": "analytics", "parameters": [ { "name": "account_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single connected account" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 7, "minimum": 1, "maximum": 365 }, "description": "Length of the reporting period in days" } ] } }, "/v1/analytics/time-series": { "get": { "operationId": "getAnalyticsTimeSeries", "summary": "Get daily time series", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeSeriesResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Daily-bucketed engagement, follower, and post counts. Use either `days` or an explicit `from`/`to` range.\n\nRequires the `analytics` scope when using an API key.", "x-fopost-scope": "analytics", "parameters": [ { "name": "account_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single connected account" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 7, "minimum": 1, "maximum": 365 } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Range start (used together with `to`)" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Range end (used together with `from`)" } ] } }, "/v1/analytics/top-posts": { "get": { "operationId": "getTopPerformingPosts", "summary": "Get top performing posts", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TopPost" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Posts ranked by engagement (or newest first with `sort=recent`). Includes platform-native posts not published through FoPost.\n\nRequires the `analytics` scope when using an API key.", "x-fopost-scope": "analytics", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 5, "minimum": 1, "maximum": 50 } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 7, "minimum": 1, "maximum": 365 } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Range start (used together with `to`)" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Range end (used together with `from`)" }, { "name": "account_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single connected account" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "recent" ] }, "description": "Pass `recent` to sort newest first instead of by engagement" }, { "name": "label", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Keep only posts carrying this label. Applied before `limit`, so it narrows the whole period rather than the page." } ] } }, "/v1/analytics/labels": { "get": { "operationId": "getLabelAnalytics", "summary": "Get per-label campaign roll-up", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LabelAnalytics" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Post metrics rolled up per label, ranked by engagement. Only posts published through FoPost carry labels, so platform-native and unlabelled posts are excluded. A post on two labels counts in full toward each.\n\nRequires the `analytics` scope when using an API key.", "x-fopost-scope": "analytics", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 7, "minimum": 1, "maximum": 365 } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Range start (used together with `to`)" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Range end (used together with `from`)" }, { "name": "account_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single connected account" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] } }, "/v1/analytics/posts-table": { "get": { "operationId": "getPostsTable", "summary": "Get posts with delivery breakdown", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostsTableResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Paginated posts of every status with per-delivery outcomes; `summary` counts the whole filtered set by status.\n\nRequires the `analytics` scope when using an API key.", "x-fopost-scope": "analytics", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "account_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single connected account" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 90 } } ] } }, "/v1/analytics/posting-streak": { "get": { "operationId": "getPostingStreak", "summary": "Get 365-day posting activity", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostingStreakResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `analytics` scope when using an API key.", "x-fopost-scope": "analytics", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] } }, "/v1/analytics/demographics": { "get": { "operationId": "getAudienceDemographics", "summary": "Get audience demographics", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DemographicsResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Latest age, gender, country, and city splits summed across the selected accounts, with the list of accounts that did or did not contribute data.\n\nRequires the `analytics` scope when using an API key.", "x-fopost-scope": "analytics", "parameters": [ { "name": "audience", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "followers", "engaged", "reached" ], "default": "followers" } }, { "name": "account_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single connected account" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] } }, "/v1/analytics/inbox": { "get": { "operationId": "getInboxAnalytics", "summary": "Get inbox analytics", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxAnalyticsResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "How the social inbox performed over the period: messages received and sent, reply coverage, median first-reply time, per-platform and per-account volume, response-time buckets and a weekday-by-hour arrival heatmap. Aggregates only.\n\nRequires the `analytics` scope when using an API key.", "x-fopost-scope": "analytics", "parameters": [ { "name": "account_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single connected account" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 7, "minimum": 1, "maximum": 365 }, "description": "Length of the reporting period in days" }, { "name": "tz", "in": "query", "required": false, "schema": { "type": "string", "default": "UTC" }, "description": "IANA time zone the heatmap is bucketed in" } ] } }, "/v1/analytics/inbox/conversations": { "get": { "operationId": "getConversationAnalytics", "summary": "Get inbox analytics per conversation", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationAnalyticsResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "The same inbox numbers broken out per thread: what each one carried and how long it waited for a reply. Aggregates only — no message text and no author.\n\nRequires the `analytics` scope when using an API key.", "x-fopost-scope": "analytics", "parameters": [ { "name": "account_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single connected account" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 7, "minimum": 1, "maximum": 365 }, "description": "Length of the reporting period in days" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "volume", "slowest", "recent" ], "default": "volume" }, "description": "Busiest first, slowest to answer first, or most recent first" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } } ] } }, "/v1/analytics/decay": { "get": { "operationId": "getContentDecay", "summary": "Get content decay by post age", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentDecayResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "How engagement accumulates as a post ages, from the repeated readings taken of each post. Each band reports where the average post had got to by that age and what share of its final engagement that was, so `half_life_bucket` says how long a post keeps earning. Posts are counted by their publish time falling inside the range.\n\nRequires the `analytics` scope when using an API key.", "x-fopost-scope": "analytics", "parameters": [ { "name": "account_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single connected account" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 30, "minimum": 1, "maximum": 365 }, "description": "Only posts published in the last this many days" } ] } }, "/v1/analytics/frequency": { "get": { "operationId": "getPostingFrequency", "summary": "Get posting cadence against engagement", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostingFrequencyResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Weekly posting cadence set against what each cadence earned per post. Weeks run Monday to Sunday in UTC and are filed under the band their own post count falls in; a week with no posts belongs to no band. `best` is the cadence with the highest engagement per post.\n\nRequires the `analytics` scope when using an API key.", "x-fopost-scope": "analytics", "parameters": [ { "name": "account_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single connected account" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 90, "minimum": 7, "maximum": 365 } } ] } }, "/v1/analytics/changes": { "get": { "operationId": "getAnalyticsChanges", "summary": "Get metric readings since a timestamp", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsChangesResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Post metric readings recorded after `since`, oldest first, with `meta.next_cursor` to pass as the next `since`. This is how an external store mirrors our metrics without refetching the whole history. Defaults to the last 7 days.\n\nRequires the `analytics` scope when using an API key.", "x-fopost-scope": "analytics", "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Return readings recorded after this instant" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500 } }, { "name": "account_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single connected account" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] } }, "/v1/analytics/posts/{id}/timeline": { "get": { "operationId": "getPostMetricTimeline", "summary": "Get one post's readings over time", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostTimelineResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Every reading held for one post, oldest first, each carrying what moved since the reading before it, with one timeline per delivery. `id` is a FoPost post id or, URL-encoded, the permalink of a post made natively on the network.\n\nRequires the `analytics` scope when using an API key.", "x-fopost-scope": "analytics", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "FoPost post id, or a URL-encoded platform permalink" } ] } }, "/v1/analytics/collect": { "post": { "operationId": "triggerAnalyticsCollect", "summary": "Trigger analytics collection", "tags": [ "Analytics" ], "responses": { "200": { "description": "Collection summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectSummaryResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "description": "Collection throttled (`too_many_requests`) — retry after `retry_after` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Collects fresh metrics for the user’s active accounts on demand. Throttled per user; when throttled the 429 body includes `retry_after` (seconds).\n\nRequires the `analytics` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "analytics", "parameters": [ { "name": "account_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single connected account" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] } }, "/v1/contacts": { "get": { "operationId": "listContacts", "summary": "List contacts", "tags": [ "Contacts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactListResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "The people behind the inbox, most recently active first. Spans every workspace the caller belongs to unless `workspace_id` names one, in which case rows omit it.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Match a display name or a handle" }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only contacts with a handle here" }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "inbox", "radar", "import" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } } ] }, "post": { "operationId": "createContact", "summary": "Create a contact", "tags": [ "Contacts" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Folds into the contact that already holds the first channel, so this can never produce a duplicate of someone the inbox has already filed.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactRequest" } } } } } }, "/v1/contacts/import": { "post": { "operationId": "importContacts", "summary": "Import contacts from a CSV", "tags": [ "Contacts" ], "responses": { "200": { "description": "Import summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportContactsResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Every row folds into an existing contact when its handle is already on file, so importing the same file twice merges rather than duplicates.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportContactsRequest" } } } } } }, "/v1/contacts/fields": { "get": { "operationId": "listCustomFields", "summary": "List custom fields", "tags": [ "Contacts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomField" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "The columns this workspace keeps about its contacts, in display order.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] }, "post": { "operationId": "createCustomField", "summary": "Create a custom field", "tags": [ "Contacts" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomField" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "A field with that key already exists in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomFieldRequest" } } } } } }, "/v1/contacts/fields/{id}": { "patch": { "operationId": "updateCustomField", "summary": "Update a custom field", "tags": [ "Contacts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomField" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "The key and the type are fixed once created; the name and options are not.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Field id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomFieldRequest" } } } } }, "delete": { "operationId": "deleteCustomField", "summary": "Delete a custom field", "tags": [ "Contacts" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Removes the field and every answer to it. This cannot be undone.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Field id" } ] } }, "/v1/contacts/{id}": { "get": { "operationId": "getContact", "summary": "Get a contact", "tags": [ "Contacts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Contact id" } ] }, "patch": { "operationId": "updateContact", "summary": "Update a contact", "tags": [ "Contacts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Contact id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactRequest" } } } } }, "delete": { "operationId": "deleteContact", "summary": "Delete a contact", "tags": [ "Contacts" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Removes the contact and its field values. The messages they sent stay in the inbox, and a later message files them again. This cannot be undone.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Contact id" } ] } }, "/v1/contacts/{id}/conversations": { "get": { "operationId": "listContactConversations", "summary": "List a contact’s conversations", "tags": [ "Contacts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactConversation" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "The threads this person appears in, newest first. Matched on their channels, so a contact merged from two handles brings both threads with it.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Contact id" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } } ] } }, "/v1/blog/settings": { "get": { "operationId": "getBlogSettings", "summary": "Get blog settings", "tags": [ "Blog" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlogSettings" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Where articles publish, how often they are planned and how long a draft waits for review.\n\nRequires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "parameters": [ { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The workspace the blog belongs to" } ] }, "patch": { "operationId": "updateBlogSettings", "summary": "Update blog settings", "tags": [ "Blog" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BlogSettings" }, { "type": "object", "properties": { "website_secret": { "type": [ "string", "null" ], "description": "The signing secret, only on the update that issued it" } } } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Setting `websiteUrl` for the first time issues a signing secret, returned once as `website_secret`. The `product_blog` target is available to admins only.\n\nRequires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBlogSettingsRequest" } } } } } }, "/v1/blog/settings/website-secret": { "post": { "operationId": "rotateBlogWebsiteSecret", "summary": "Rotate the website signing secret", "tags": [ "Blog" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "website_secret": { "type": "string" } }, "required": [ "website_secret" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "The new secret is returned once and never readable again.\n\nRequires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" } }, "required": [ "workspaceId" ] } } } } } }, "/v1/blog/settings/website-test": { "post": { "operationId": "testBlogWebsite", "summary": "Send a signed test article to the website", "tags": [ "Blog" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "http_status": { "type": "integer", "description": "What the website answered" } }, "required": [ "http_status" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "The website refused or could not be reached (`website_test_failed`); `http_status` carries its answer when it gave one", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Answers 200 when the site accepted it, 502 (`website_test_failed`) with the reason otherwise.\n\nRequires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" } }, "required": [ "workspaceId" ] } } } } } }, "/v1/blog/keywords": { "get": { "operationId": "listBlogKeywords", "summary": "List the keyword plan", "tags": [ "Blog" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BlogKeyword" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "parameters": [ { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The workspace the blog belongs to" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated: suggested, planned, written, dismissed" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500 } } ] }, "post": { "operationId": "createBlogKeyword", "summary": "Add a keyword", "tags": [ "Blog" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlogKeyword" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "keyword": { "type": "string" }, "plannedFor": { "type": "string", "format": "date" } }, "required": [ "workspaceId", "keyword" ] } } } } } }, "/v1/blog/keywords/plan": { "post": { "operationId": "planBlogKeywords", "summary": "Research keywords and fill the calendar", "tags": [ "Blog" ], "responses": { "202": { "description": "Queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "queued" ] } }, "required": [ "status" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Runs in the background and spends AI credits. Seeds are derived from the site description when omitted.\n\nRequires the `ai` scope when using an API key.", "x-fopost-scope": "ai", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "seeds": { "type": "array", "items": { "type": "string" } } }, "required": [ "workspaceId" ] } } } } } }, "/v1/blog/keywords/{id}": { "patch": { "operationId": "updateBlogKeyword", "summary": "Update a keyword", "tags": [ "Blog" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlogKeyword" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Keyword id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The workspace the blog belongs to" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "suggested", "planned", "written", "dismissed" ] }, "plannedFor": { "type": [ "string", "null" ], "format": "date" } } } } } } }, "delete": { "operationId": "deleteBlogKeyword", "summary": "Remove a keyword", "tags": [ "Blog" ], "responses": { "204": { "description": "Removed", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Keyword id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The workspace the blog belongs to" } ] } }, "/v1/blog/articles": { "get": { "operationId": "listBlogArticles", "summary": "List articles", "tags": [ "Blog" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BlogArticle" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "parameters": [ { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The workspace the blog belongs to" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated statuses" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200 } } ] }, "post": { "operationId": "createBlogArticle", "summary": "Request an article", "tags": [ "Blog" ], "responses": { "202": { "description": "Queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlogArticle" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Queues the writer: research, outline, body, meta and images run in the background and the draft lands in review. Spends AI credits.\n\nRequires the `ai` scope when using an API key.", "x-fopost-scope": "ai", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBlogArticleRequest" } } } } } }, "/v1/blog/articles/{id}": { "get": { "operationId": "getBlogArticle", "summary": "Get an article", "tags": [ "Blog" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlogArticleFull" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Article id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The workspace the blog belongs to" } ] }, "patch": { "operationId": "updateBlogArticle", "summary": "Edit an article", "tags": [ "Blog" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlogArticleFull" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Only a draft, scheduled, failed or rejected article can be edited.\n\nRequires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Article id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The workspace the blog belongs to" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBlogArticleRequest" } } } } }, "delete": { "operationId": "deleteBlogArticle", "summary": "Delete an article", "tags": [ "Blog" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Article id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The workspace the blog belongs to" } ] } }, "/v1/blog/articles/{id}/regenerate": { "post": { "operationId": "regenerateBlogArticle", "summary": "Rewrite an article", "tags": [ "Blog" ], "responses": { "202": { "description": "Queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlogArticle" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Runs the writer again on the same brief. Spends AI credits.\n\nRequires the `ai` scope when using an API key.", "x-fopost-scope": "ai", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Article id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The workspace the blog belongs to" } ] } }, "/v1/blog/articles/{id}/publish": { "post": { "operationId": "publishBlogArticle", "summary": "Publish an article now", "tags": [ "Blog" ], "responses": { "202": { "description": "Publishing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlogArticle" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Sends the draft to the configured target without waiting for the review window.\n\nRequires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Article id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The workspace the blog belongs to" } ] } }, "/v1/blog/articles/{id}/reject": { "post": { "operationId": "rejectBlogArticle", "summary": "Reject a draft", "tags": [ "Blog" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlogArticle" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Article id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The workspace the blog belongs to" } ] } }, "/v1/broadcasts": { "get": { "operationId": "listBroadcasts", "summary": "List broadcasts", "tags": [ "Broadcasts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastListResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Newest first. Spans every workspace the caller belongs to unless `workspace_id` names one, in which case rows omit it.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "scheduled", "sending", "sent", "cancelled" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } } ] }, "post": { "operationId": "createBroadcast", "summary": "Create a broadcast", "tags": [ "Broadcasts" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Broadcast" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Creates it without sending. Give `scheduled_at` to have it go out on its own, or call send when you are ready.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBroadcastRequest" } } } } } }, "/v1/broadcasts/{id}": { "get": { "operationId": "getBroadcast", "summary": "Get a broadcast", "tags": [ "Broadcasts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Broadcast" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Broadcast id" } ] }, "patch": { "operationId": "updateBroadcast", "summary": "Update a broadcast", "tags": [ "Broadcasts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Broadcast" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Only a draft or scheduled broadcast can be edited.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Broadcast id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBroadcastRequest" } } } } }, "delete": { "operationId": "deleteBroadcast", "summary": "Delete a broadcast", "tags": [ "Broadcasts" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Removes the broadcast and its recipient records. Messages already sent stay in the conversations they went to. This cannot be undone.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Broadcast id" } ] } }, "/v1/broadcasts/{id}/send": { "post": { "operationId": "sendBroadcast", "summary": "Send a broadcast", "tags": [ "Broadcasts" ], "responses": { "200": { "description": "Sending started", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "recipients": { "type": "integer" } }, "required": [ "id", "status", "recipients" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Freezes the recipient list and starts sending. Contacts a network’s messaging window has closed on are skipped with `window_closed` rather than attempted, so the number sent can be lower than the audience. Also requires the `publish` scope.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Broadcast id" } ] } }, "/v1/broadcasts/{id}/cancel": { "post": { "operationId": "cancelBroadcast", "summary": "Cancel a broadcast", "tags": [ "Broadcasts" ], "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" } }, "required": [ "id", "status" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Stops it where it stands. Anyone not yet written to stays unsent; messages already delivered are not recalled. Also requires the `publish` scope.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Broadcast id" } ] } }, "/v1/broadcasts/{id}/recipients": { "get": { "operationId": "listBroadcastRecipients", "summary": "List a broadcast’s recipients", "tags": [ "Broadcasts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastRecipientListResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "One row per contact, with what became of their message. A skipped row carries the reason.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Broadcast id" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "sent", "skipped", "failed" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 } } ] } }, "/v1/sequences": { "get": { "operationId": "listSequences", "summary": "List sequences", "tags": [ "Broadcasts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequenceListResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } } ] }, "post": { "operationId": "createSequence", "summary": "Create a sequence", "tags": [ "Broadcasts" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sequence" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "A series of messages, each a delay after the one before. Nobody is enrolled until you enroll them.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSequenceRequest" } } } } } }, "/v1/sequences/{id}": { "get": { "operationId": "getSequence", "summary": "Get a sequence", "tags": [ "Broadcasts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sequence" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Sequence id" } ] }, "patch": { "operationId": "updateSequence", "summary": "Update a sequence", "tags": [ "Broadcasts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sequence" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Pausing it stops every enrollment from firing without ending any of them; resuming picks them up where they stood.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Sequence id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSequenceRequest" } } } } }, "delete": { "operationId": "deleteSequence", "summary": "Delete a sequence", "tags": [ "Broadcasts" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Removes the sequence and every enrollment on it. Messages already sent stay in the conversations they went to. This cannot be undone.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Sequence id" } ] } }, "/v1/sequences/{id}/enroll": { "post": { "operationId": "enrollInSequence", "summary": "Enroll contacts in a sequence", "tags": [ "Broadcasts" ], "responses": { "200": { "description": "Enrolled", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "enrolled": { "type": "integer" } }, "required": [ "id", "enrolled" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Re-enrolling someone restarts their walk from the first step rather than running two in parallel. Also requires the `publish` scope.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Sequence id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollRequest" } } } } } }, "/v1/sequences/{id}/unenroll": { "post": { "operationId": "unenrollFromSequence", "summary": "Unenroll contacts from a sequence", "tags": [ "Broadcasts" ], "responses": { "200": { "description": "Unenrolled", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "stopped": { "type": "integer" } }, "required": [ "id", "stopped" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Nothing further fires for them. Also requires the `publish` scope.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Sequence id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnenrollRequest" } } } } } }, "/v1/sequences/{id}/enrollments": { "get": { "operationId": "listEnrollments", "summary": "List a sequence’s enrollments", "tags": [ "Broadcasts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentListResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Who is on it, what step they are at, and when the next one is due.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Sequence id" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 } } ] } }, "/v1/automations": { "get": { "operationId": "listAutomations", "summary": "List automations", "tags": [ "Automations" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Automation" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `automations` scope when using an API key.", "x-fopost-scope": "automations" }, "post": { "operationId": "createAutomation", "summary": "Create an automation", "tags": [ "Automations" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationCreated" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Creates a trigger → pipeline workflow. The webhook trigger `secret` is returned only in this response.\n\nRequires the `automations` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "automations", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAutomationRequest" } } } } } }, "/v1/automations/stats": { "get": { "operationId": "getAutomationStats", "summary": "Get automation stats", "tags": [ "Automations" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationStatsResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Totals plus run counts by status for the last 24 hours and the 10 latest runs.\n\nRequires the `automations` scope when using an API key.", "x-fopost-scope": "automations" } }, "/v1/automations/{id}": { "get": { "operationId": "getAutomation", "summary": "Get an automation", "tags": [ "Automations" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationDetail" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `automations` scope when using an API key.", "x-fopost-scope": "automations", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Automation id" } ] }, "put": { "operationId": "updateAutomation", "summary": "Update an automation", "tags": [ "Automations" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationUpdated" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "When `graph` or `steps` is provided the whole graph is replaced.\n\nRequires the `automations` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "automations", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Automation id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAutomationRequest" } } } } }, "delete": { "operationId": "deleteAutomation", "summary": "Delete an automation", "tags": [ "Automations" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `automations` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "automations", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Automation id" } ] } }, "/v1/automations/{id}/toggle": { "post": { "operationId": "toggleAutomation", "summary": "Toggle an automation on or off", "tags": [ "Automations" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "active": { "type": "boolean" } }, "required": [ "id", "active" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `automations` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "automations", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Automation id" } ] } }, "/v1/automations/{id}/runs": { "get": { "operationId": "listAutomationRuns", "summary": "List automation runs", "tags": [ "Automations" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationRun" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `automations` scope when using an API key.", "x-fopost-scope": "automations", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Automation id" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 30, "minimum": 1, "maximum": 100 } } ] } }, "/v1/automations/{id}/runs/{runId}": { "get": { "operationId": "getAutomationRun", "summary": "Get an automation run", "tags": [ "Automations" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRunDetail" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "The run id is not a number (`validation_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Includes per-step execution logs.\n\nRequires the `automations` scope when using an API key.", "x-fopost-scope": "automations", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Automation id" }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Run id" } ] } }, "/v1/automations/{id}/trigger": { "post": { "operationId": "triggerAutomationWebhook", "summary": "Trigger an automation via webhook", "tags": [ "Automations" ], "responses": { "200": { "description": "Run started", "content": { "application/json": { "schema": { "type": "object", "properties": { "run_id": { "type": "integer" }, "triggered": { "type": "boolean" } }, "required": [ "run_id", "triggered" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Missing or wrong `x-automation-secret` (`unauthorized`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "The automation is inactive or refused the trigger (`invalid_state`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Public endpoint for `api_webhook` automations. Authenticated by the automation’s secret in the `x-automation-secret` header (returned when the automation was created), not by an API key. The JSON body (optional) becomes the trigger payload.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Automation id" } ], "requestBody": { "required": false, "description": "Arbitrary trigger payload", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [] } }, "/v1/knowledge/sources": { "get": { "operationId": "listKnowledgeSources", "summary": "List knowledge sources", "tags": [ "Knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeSource" } }, "available": { "type": "boolean" } }, "required": [ "data", "available" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "What the workspace has told FoPost about itself. `available` is false when this deployment cannot index sources at all.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] }, "post": { "operationId": "createKnowledgeSource", "summary": "Add a knowledge source", "tags": [ "Knowledge" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeSource" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "description": "Adds a source and queues it for indexing, so it comes back `pending`. A `faq` or `text` source needs `content`, a `url` source needs `url`, and a `file` source needs `media_id` pointing at a plain-text or CSV item in the same workspace.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "faq", "text", "url", "file" ] }, "title": { "type": "string" }, "content": { "type": "string" }, "url": { "type": "string" }, "media_id": { "type": "string", "format": "uuid" }, "brand_voice_id": { "type": [ "string", "null" ], "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" } }, "required": [ "kind", "title" ] } } } } } }, "/v1/knowledge/sources/{id}": { "patch": { "operationId": "updateKnowledgeSource", "summary": "Update a knowledge source", "tags": [ "Knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeSource" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Changing `content` or `url` makes the stored passages stale, so the source returns to `pending` and is re-indexed.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "content": { "type": "string" }, "url": { "type": "string" }, "brand_voice_id": { "type": [ "string", "null" ], "format": "uuid" } } } } } } }, "delete": { "operationId": "deleteKnowledgeSource", "summary": "Delete a knowledge source", "tags": [ "Knowledge" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Removes the source and every passage indexed from it.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/knowledge/sources/{id}/sync": { "post": { "operationId": "syncKnowledgeSource", "summary": "Re-index a knowledge source", "tags": [ "Knowledge" ], "responses": { "202": { "description": "Queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" } }, "required": [ "id", "status" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "description": "Queues the source to be read and indexed again — a `url` source is re-fetched. Answers 202 immediately; poll the source for its status.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } } }, "/v1/knowledge/search": { "get": { "operationId": "searchKnowledge", "summary": "Search the knowledge base", "tags": [ "Knowledge" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeMatch" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "The AI balance is empty (`insufficient_credits`, with `upgrade_url`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "The search could not run (`search_failed`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "description": "The passages closest to a question, best first. An empty list is the honest answer when nothing stored answers it.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The question, in plain words" }, { "name": "top_k", "in": "query", "required": false, "schema": { "type": "integer", "default": 5, "minimum": 1, "maximum": 20 } }, { "name": "brand_voice_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Narrow to one brand" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] } }, "/v1/inbox": { "get": { "operationId": "listInboxItems", "summary": "List inbox items", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxListResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Comments, mentions, reviews and direct messages across the connected accounts, newest first. Without `workspace_id` the list spans every workspace the caller belongs to and each item carries its `workspace_id`.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "comment", "mention", "dm", "review" ] } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "unread", "read", "resolved", "snoozed" ] } }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "account_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "post_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Comments under one FoPost post" }, { "name": "post_external_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comments under one platform post, including posts not published here" }, { "name": "conversation_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "One DM thread" }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "inbound", "outbound" ] } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Searches text and author" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "newest", "oldest", "unanswered" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "include_raw", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Adds each item's stored platform payload as `raw` (one workspace, bypassed users only)" } ] } }, "/v1/inbox/unread-count": { "get": { "operationId": "getInboxUnreadCount", "summary": "Count unread items", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" } }, "required": [ "count" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] } }, "/v1/inbox/accounts": { "get": { "operationId": "listInboxAccounts", "summary": "List accounts with inbox coverage", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InboxAccount" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Every active connected account, each flagged with whether comments and DMs can be read for it yet.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] } }, "/v1/inbox/platforms": { "get": { "operationId": "listInboxPlatforms", "summary": "List inbox-capable platforms", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InboxPlatform" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Which networks feed the inbox today, and which are coming. Not tenant data.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox" } }, "/v1/inbox/posts": { "get": { "operationId": "listInboxThreads", "summary": "List comment threads by post", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxThreadListResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "One row per platform post that has collected comments (`kind=comments`, the default), per post the account was tagged in (`kind=mentions`), or per review left on the business (`kind=reviews`). Fetch a thread's items with `GET /v1/inbox?account_id=…&post_external_id=…`.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "comments", "mentions", "reviews" ], "default": "comments" } }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "account_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "unread", "read", "resolved", "snoozed" ] } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "newest", "oldest", "unanswered" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } } ] } }, "/v1/inbox/conversations": { "get": { "operationId": "listInboxConversations", "summary": "List DM conversations", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxConversationListResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "One row per direct-message thread, latest first. Fetch a thread with `GET /v1/inbox?account_id=…&conversation_id=…`.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "account_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "unread", "read", "resolved", "snoozed" ] } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "newest", "oldest", "unanswered" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } } ] }, "post": { "operationId": "startInboxConversation", "summary": "Start a conversation", "tags": [ "Inbox" ], "responses": { "201": { "description": "Sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation_id": { "type": [ "string", "null" ] }, "item": { "oneOf": [ { "$ref": "#/components/schemas/InboxItem" }, { "type": "null" } ] } }, "required": [ "conversation_id", "item" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account is disconnected or the platform cannot open a DM", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "description": "The platform is rate limiting this account (`rate_limited`, with `retry_at`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "502": { "description": "The platform refused it; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Opens a DM: by `handle` from `account_id`, or as a private reply to an inbox comment by `comment_id` (Facebook and Instagram, where that is the only way). Also requires the `publish` scope.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartConversationRequest" } } } } } }, "/v1/inbox/read": { "post": { "operationId": "markInboxThreadRead", "summary": "Mark a thread read", "tags": [ "Inbox" ], "responses": { "204": { "description": "Marked read", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Reads every item in one comment thread (`post_external_id`) or DM thread (`conversation_id`) on the account, the way opening a chat does.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkInboxReadRequest" } } } } } }, "/v1/inbox/refresh": { "post": { "operationId": "refreshInbox", "summary": "Poll the inbox now", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxRefreshResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Fetches new comments and messages for every inbox-capable account in the workspace instead of waiting for the next scheduled poll. Platforms that bill per read are read on this call.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshInboxRequest" } } } } } }, "/v1/inbox/approvals": { "get": { "operationId": "listInboxApprovals", "summary": "List replies awaiting approval", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InboxApproval" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Replies an automation or the agent drafted that a person still has to send. Nothing reaches a platform until one is approved.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] } }, "/v1/inbox/approvals/{id}/approve": { "post": { "operationId": "approveInboxReply", "summary": "Approve and send a drafted reply", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "outcome": { "type": "string" } }, "required": [ "id", "outcome" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The reply was already decided", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Approval id" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecideInboxReplyRequest" } } } } } }, "/v1/inbox/approvals/{id}/reject": { "post": { "operationId": "rejectInboxReply", "summary": "Reject a drafted reply", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "outcome": { "type": "string" } }, "required": [ "id", "outcome" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The reply was already decided", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Approval id" } ] } }, "/v1/inbox/{id}": { "patch": { "operationId": "updateInboxItem", "summary": "Change an item’s state, or edit our own comment", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxItem" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account is disconnected or the platform cannot edit it", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Mark it read, resolved, unread, or snoozed until a time. A body with `text` instead edits a comment the account wrote, on the platform, where `can_edit` is true; that also requires the `publish` scope.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Inbox item id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UpdateInboxItemRequest" }, { "$ref": "#/components/schemas/EditInboxCommentRequest" } ] } } } } }, "delete": { "operationId": "deleteInboxItem", "summary": "Delete a comment on the platform", "tags": [ "Inbox" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account is disconnected or the platform cannot delete it", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Removes the comment from the platform where it was left, whether someone else wrote it or it is our own reply. Only where `can_delete` is true. Deleting our own reply also requires the `publish` scope.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Inbox item id" } ] } }, "/v1/inbox/{id}/reply": { "post": { "operationId": "replyToInboxItem", "summary": "Reply to an item", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxReplyResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account is disconnected or the platform cannot reply", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "description": "The platform is rate limiting this account (`rate_limited`, with `retry_at`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "502": { "description": "The platform refused the reply; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "503": { "description": "This deployment holds no credentials for the platform yet", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Sends the reply on the platform as the connected account and settles the item. Only where `can_reply` is true. A DM reply may carry `media_ids` (sent as short-lived signed links) and `quick_replies`; either also requires the `publish` scope.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Inbox item id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxReplyRequest" } } } } } }, "/v1/inbox/{id}/hide": { "post": { "operationId": "hideInboxItem", "summary": "Hide a comment on the platform", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxItem" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account is disconnected or the platform cannot hide it", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Inbox item id" } ] } }, "/v1/inbox/{id}/unhide": { "post": { "operationId": "unhideInboxItem", "summary": "Unhide a comment on the platform", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxItem" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account is disconnected or the platform cannot unhide it", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Inbox item id" } ] } }, "/v1/inbox/{id}/like": { "post": { "operationId": "likeInboxItem", "summary": "Like an item", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxItem" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account is disconnected or the platform cannot like it", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "description": "The platform is rate limiting this account (`rate_limited`, with `retry_at`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "502": { "description": "The platform refused it; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "A like, an upvote on Reddit, a favourite on Mastodon. Only where `can_like` is true. Also requires the `publish` scope.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Inbox item id" } ] } }, "/v1/inbox/{id}/unlike": { "post": { "operationId": "unlikeInboxItem", "summary": "Remove our like", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxItem" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account is disconnected or the platform cannot unlike it", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "description": "The platform is rate limiting this account (`rate_limited`, with `retry_at`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "502": { "description": "The platform refused it; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Only where `can_like` is true. Also requires the `publish` scope.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Inbox item id" } ] } }, "/v1/inbox/{id}/pin": { "post": { "operationId": "pinInboxItem", "summary": "Pin our own comment", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxItem" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account is disconnected or the platform cannot pin it", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "description": "The platform is rate limiting this account (`rate_limited`, with `retry_at`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "502": { "description": "The platform refused it; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Only where `can_pin` is true. Also requires the `publish` scope.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Inbox item id" } ] } }, "/v1/inbox/{id}/unpin": { "post": { "operationId": "unpinInboxItem", "summary": "Unpin our own comment", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxItem" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account is disconnected or the platform cannot unpin it", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "description": "The platform is rate limiting this account (`rate_limited`, with `retry_at`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "502": { "description": "The platform refused it; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Only where `can_pin` is true. Also requires the `publish` scope.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Inbox item id" } ] } }, "/v1/inbox/{id}/react": { "post": { "operationId": "reactToInboxItem", "summary": "React to a message", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxItem" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account is disconnected or the platform has no reactions", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "description": "The platform is rate limiting this account (`rate_limited`, with `retry_at`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "502": { "description": "The platform refused it; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Only where `can_react` is true. Instagram has one reaction, a heart. Also requires the `publish` scope.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Inbox item id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReactInboxItemRequest" } } } } } }, "/v1/inbox/conversations/{id}": { "delete": { "operationId": "deleteInboxConversation", "summary": "Delete a conversation from the inbox", "tags": [ "Inbox" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Removes a DM thread from the inbox only. No network lets an app delete a conversation, so the platform keeps its copy and the thread returns if the other side writes again.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The conversation id of a DM" }, { "name": "account_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The connected account the thread belongs to" } ] } }, "/v1/inbox/conversations/{id}/typing": { "post": { "operationId": "setInboxTyping", "summary": "Show the typing indicator", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "typing": { "type": "boolean" } }, "required": [ "typing" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account is disconnected or the platform has no indicator", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Shows or clears the typing indicator in a DM thread. Also requires the `publish` scope.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The conversation id of a DM" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxTypingRequest" } } } } } }, "/v1/inbox/conversations/{id}/handover": { "post": { "operationId": "setInboxHandover", "summary": "Hand over a Messenger thread", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "app_id": { "type": [ "string", "null" ] }, "control": { "type": "string", "enum": [ "passed", "taken" ] } }, "required": [ "app_id", "control" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The account is disconnected or the network has no hand-over", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Passes the thread to another Meta app, or takes it back when no `app_id` is given. Also requires the `publish` scope.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The conversation id of a DM" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxHandoverRequest" } } } } } }, "/v1/inbox/{id}/attachments/{index}": { "get": { "operationId": "getInboxAttachment", "summary": "Fetch a message attachment", "tags": [ "Inbox" ], "responses": { "200": { "description": "The attachment bytes", "content": { "*/*": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "description": "Attachment is too large to pass through", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "415": { "description": "Attachment type not supported", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Streams one attachment of a DM through the API. The URL grants nothing on its own: workspace membership is checked on every request. Accepts the session cookie as well as a header credential, so a plain `` works in the dashboard.\n\nRequires the `inbox` scope when using an API key.", "x-fopost-scope": "inbox", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Inbox item id" }, { "name": "index", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Position in the item’s `attachments`" }, { "name": "variant", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "preview" ] } } ] } }, "/v1/ads": { "get": { "operationId": "listAds", "summary": "List ads", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Ad" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Boosts and standalone ads created through FoPost, with the insights from their last refresh. Ads made elsewhere on the same ad accounts are `GET /v1/ads/external`.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] }, "post": { "operationId": "createAd", "summary": "Create an ad", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Ad" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Creates a campaign, ad set and ad on the Meta ad account from the given creative. The ad starts paused unless `paused` is false. Also requires the `publish` scope.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdRequest" } } } } } }, "/v1/ads/boost": { "post": { "operationId": "boostPost", "summary": "Boost a published post", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Ad" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Promotes a post FoPost already published to the given account. Candidates come from `GET /v1/ads/boostable`. The boost starts paused unless `paused` is false. Also requires the `publish` scope.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoostPostRequest" } } } } } }, "/v1/ads/{id}": { "patch": { "operationId": "setAdStatus", "summary": "Pause or resume an ad", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Ad" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Also requires the `publish` scope.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Ad id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetAdStatusRequest" } } } } }, "delete": { "operationId": "deleteAd", "summary": "Delete an ad", "tags": [ "Ads" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Ends delivery and deletes the ad on Meta, then removes it here. Also requires the `publish` scope.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Ad id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] } }, "/v1/ads/{id}/refresh": { "post": { "operationId": "refreshAd", "summary": "Refresh an ad’s status and insights", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Ad" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Reads the delivery status and lifetime insights from Meta and stores them.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Ad id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] } }, "/v1/ads/external": { "get": { "operationId": "listExternalAds", "summary": "List ads made outside FoPost", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalAd" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Ads that live on the connected ad accounts but were not created here. Read live from Meta on every call and never stored.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] } }, "/v1/ads/boostable": { "get": { "operationId": "listBoostablePosts", "summary": "List posts that can be boosted", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BoostablePost" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Published posts with a delivery on an account a Meta Ads connection reaches.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] } }, "/v1/ads/connections": { "get": { "operationId": "listAdConnections", "summary": "List Meta Ads connections", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AdConnection" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] } }, "/v1/ads/connections/meta/authorize": { "post": { "operationId": "authorizeMetaAds", "summary": "Start a Meta Ads connection", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "A saved card is required before another connection", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "The workspace already has an active Meta Ads connection", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Meta Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Returns the Meta login URL. The user who calls this must finish the login in their own browser session: the callback checks that the same user came back. An ad connection fills a connected-account slot, so past the free allowance a saved card is required.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectMetaAdsRequest" } } } } } }, "/v1/ads/connections/{id}": { "delete": { "operationId": "deleteAdConnection", "summary": "Remove a Meta Ads connection", "tags": [ "Ads" ], "responses": { "204": { "description": "Removed", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Also deletes every ad record FoPost created through it.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Connection id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] } }, "/v1/ads/providers": { "get": { "operationId": "listAdProviders", "summary": "List ad networks", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AdProvider" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Every ad network, with whether it can be connected on this deployment.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads" } }, "/v1/ads/connections/google/authorize": { "post": { "operationId": "authorizeGoogleAds", "summary": "Start a Google Ads connection", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "A saved card is required before another connection", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "The workspace already has an active Google Ads connection", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Returns the Google login URL. The user who calls this must finish the login in their own browser session: the callback checks that the same user came back. An ad connection fills a connected-account slot, so past the free allowance a saved card is required.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectMetaAdsRequest" } } } } } }, "/v1/ads/google/keywords": { "get": { "operationId": "listGoogleKeywords", "summary": "List Google Ads keywords", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GoogleKeyword" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Keywords on the account, or on one ad group. Google Ads only: on another network this answers 400.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "customer_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Google Ads customer id, digits only" }, { "name": "ad_group_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Limit to one ad group" } ] }, "post": { "operationId": "createGoogleKeyword", "summary": "Add a keyword", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Adds a keyword to an ad group. Needs the `publish` scope: it goes live.\n\nRequires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGoogleKeywordRequest" } } } } } }, "/v1/ads/google/keywords/{id}": { "patch": { "operationId": "updateGoogleKeyword", "summary": "Pause, resume or rebid a keyword", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Keyword object id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGoogleKeywordRequest" } } } } }, "delete": { "operationId": "deleteGoogleKeyword", "summary": "Remove a keyword", "tags": [ "Ads" ], "responses": { "204": { "description": "Removed", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Keyword object id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleAdsScopeRequest" } } } } } }, "/v1/ads/google/keyword-ideas": { "post": { "operationId": "googleKeywordIdeas", "summary": "Find keyword ideas", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GoogleKeywordIdea" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Ideas from seed keywords, a landing page, or both.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleKeywordIdeasRequest" } } } } } }, "/v1/ads/google/keyword-metrics": { "post": { "operationId": "googleKeywordMetrics", "summary": "Read historical keyword metrics", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GoogleKeywordIdea" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleKeywordIdeasRequest" } } } } } }, "/v1/ads/google/search-terms": { "get": { "operationId": "listGoogleSearchTerms", "summary": "List search terms", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GoogleSearchTerm" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "What people actually searched, with the metrics each term earned.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "customer_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Google Ads customer id, digits only" }, { "name": "since", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "until", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } } ] } }, "/v1/ads/google/bid-strategies": { "get": { "operationId": "listGoogleBidStrategies", "summary": "List portfolio bid strategies", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GoogleBidStrategy" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "customer_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Google Ads customer id, digits only" } ] }, "post": { "operationId": "createGoogleBidStrategy", "summary": "Create a bid strategy", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleAdsScopeRequest" } } } } } }, "/v1/ads/google/ad-schedule": { "get": { "operationId": "listGoogleAdSchedule", "summary": "Read a campaign ad schedule", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GoogleAdScheduleSlot" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "customer_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Google Ads customer id, digits only" }, { "name": "campaign_id", "in": "query", "required": true, "schema": { "type": "string" } } ] }, "put": { "operationId": "setGoogleAdSchedule", "summary": "Replace a campaign ad schedule", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "slots": { "type": "integer" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Google has no partial edit for a schedule: the slots given replace every slot on the campaign.\n\nRequires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleAdsScopeRequest" } } } } } }, "/v1/ads/google/negative-keywords": { "get": { "operationId": "listGoogleNegativeKeywordLists", "summary": "List negative keyword lists", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GoogleSharedSet" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "customer_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Google Ads customer id, digits only" } ] }, "post": { "operationId": "createGoogleNegativeKeywordList", "summary": "Create a negative keyword list", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleAdsScopeRequest" } } } } } }, "/v1/ads/google/negative-keywords/keywords": { "post": { "operationId": "addGoogleNegativeKeywords", "summary": "Add keywords to a negative list", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "added": { "type": "integer" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleAdsScopeRequest" } } } } } }, "/v1/ads/google/negative-keywords/attach": { "post": { "operationId": "attachGoogleNegativeKeywordList", "summary": "Attach a negative list to a campaign", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "campaignId": { "type": "string" }, "sharedSetId": { "type": "string" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleAdsScopeRequest" } } } } } }, "/v1/ads/google/assets": { "get": { "operationId": "listGoogleAssets", "summary": "List account assets", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleAssetsResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Sitelinks, callouts and structured snippets, with where each one is attached.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "customer_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Google Ads customer id, digits only" } ] }, "post": { "operationId": "createGoogleAsset", "summary": "Create an asset", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGoogleAssetRequest" } } } } } }, "/v1/ads/google/assets/attach": { "post": { "operationId": "attachGoogleAsset", "summary": "Attach an asset to the account or a campaign", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "assetId": { "type": "string" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleAdsScopeRequest" } } } } } }, "/v1/ads/google/assets/{id}": { "delete": { "operationId": "deleteGoogleAsset", "summary": "Detach an asset", "tags": [ "Ads" ], "responses": { "204": { "description": "Detached", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "An asset itself is permanent on Google, so this removes every link that puts it under an ad.\n\nRequires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Asset object id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleAdsScopeRequest" } } } } } }, "/v1/ads/google/asset-groups": { "get": { "operationId": "listGoogleAssetGroups", "summary": "List Performance Max asset groups", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GoogleAssetGroup" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "customer_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Google Ads customer id, digits only" }, { "name": "campaign_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Limit to one campaign" } ] }, "post": { "operationId": "createGoogleAssetGroup", "summary": "Create a Performance Max asset group", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGoogleAssetGroupRequest" } } } } } }, "/v1/ads/google/asset-groups/{id}": { "patch": { "operationId": "updateGoogleAssetGroup", "summary": "Rename, pause or resume an asset group", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Asset group object id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleAdsScopeRequest" } } } } }, "delete": { "operationId": "deleteGoogleAssetGroup", "summary": "Remove an asset group", "tags": [ "Ads" ], "responses": { "204": { "description": "Removed", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Asset group object id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleAdsScopeRequest" } } } } } }, "/v1/ads/google/recommendations": { "get": { "operationId": "listGoogleRecommendations", "summary": "List recommendations", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GoogleRecommendation" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Google’s own read on what the account should change next, with the impact it projects. `types` narrows to a comma-separated list of recommendation types.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "customer_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Google Ads customer id, digits only" }, { "name": "types", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/v1/ads/google/optimization-score": { "get": { "operationId": "getGoogleOptimizationScore", "summary": "Read the optimization score", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GoogleOptimizationScore" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "The account’s score and weight, and the score of each live campaign.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "customer_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Google Ads customer id, digits only" } ] } }, "/v1/ads/google/recommendations/apply": { "post": { "operationId": "applyGoogleRecommendations", "summary": "Apply recommendations", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "applied": { "type": "integer" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Applies each recommendation, which changes what the live account serves or bids. An id that does not name a recommendation on `customerId` is not found.\n\nRequires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleAdsScopeRequest" } } } } } }, "/v1/ads/google/recommendations/dismiss": { "post": { "operationId": "dismissGoogleRecommendations", "summary": "Dismiss recommendations", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "dismissed": { "type": "integer" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Hides each recommendation so Google stops surfacing it.\n\nRequires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleAdsScopeRequest" } } } } } }, "/v1/ads/google/local-services": { "get": { "operationId": "listGoogleLocalServicesLeads", "summary": "List Local Services leads", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GoogleLocalServicesLead" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Leads from Local Services Ads, read live and never stored.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "customer_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Google Ads customer id, digits only" }, { "name": "since", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "until", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } } ] } }, "/v1/ads/google/conversions": { "get": { "operationId": "listGoogleConversionActions", "summary": "List conversion actions", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GoogleConversionAction" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "customer_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Google Ads customer id, digits only" } ] }, "post": { "operationId": "createGoogleConversionAction", "summary": "Create a conversion action", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Requires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleAdsScopeRequest" } } } } } }, "/v1/ads/google/conversions/upload": { "post": { "operationId": "uploadGoogleConversions", "summary": "Upload click conversions", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uploaded": { "type": "integer" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Offline conversions, matched to a click by `gclid`, `gbraid` or `wbraid`.\n\nRequires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadGoogleConversionsRequest" } } } } } }, "/v1/ads/google/conversions/adjustments": { "post": { "operationId": "uploadGoogleConversionAdjustments", "summary": "Upload conversion adjustments", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uploaded": { "type": "integer" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Restate, retract or enhance a conversion already counted.\n\nRequires the `publish` scope when using an API key.", "x-fopost-scope": "publish", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleAdsScopeRequest" } } } } } }, "/v1/ads/insights/query": { "post": { "operationId": "runGoogleInsightsQuery", "summary": "Run a GAQL query", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object" } } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Google Ads is not configured on this deployment", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "A raw read-only Google Ads Query Language SELECT against one customer. The customer comes from `customerId`, never from the query text, and anything that is not a SELECT is refused before the connection is touched. Google Ads only.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleInsightsQueryRequest" } } } } } }, "/v1/ads/sources": { "get": { "operationId": "listAdSources", "summary": "List ad accounts and Pages", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AdSource" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Every Meta Ads connection with the ad accounts and Pages its grant reaches.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] } }, "/v1/ads/goals": { "get": { "operationId": "listAdGoals", "summary": "List the goals a connection can run", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "What the network can run on this deployment. A goal it cannot run is absent here and refused as `unsupported` if asked for anyway.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ] } }, "/v1/ads/catalogs": { "get": { "operationId": "listAdCatalogs", "summary": "List product catalogs", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdCatalogsResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Catalogs the connection's business portfolios own or are a partner on. Read live from Meta and never stored.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ] }, "post": { "operationId": "createAdCatalog", "summary": "Create a product catalog", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdCatalog" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Created on `businessId`, or on the connection's business portfolio when omitted. A business the connection does not reach answers 404; a connection that reaches no portfolio answers 400.\n\nRequires the `ads` and `publish` scopes when using an API key.", "x-fopost-scope": "ads", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdCatalogRequest" } } } } } }, "/v1/ads/catalogs/{id}": { "get": { "operationId": "getAdCatalog", "summary": "Get a product catalog", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdCatalog" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta catalog id" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ] }, "patch": { "operationId": "updateAdCatalog", "summary": "Rename a product catalog", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdCatalog" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` and `publish` scopes when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta catalog id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdCatalogRequest" } } } } }, "delete": { "operationId": "deleteAdCatalog", "summary": "Delete a product catalog", "tags": [ "Ads" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Deletes it on Meta with every product, feed and set beneath it.\n\nRequires the `ads` and `publish` scopes when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta catalog id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ] } }, "/v1/ads/catalogs/{id}/products": { "get": { "operationId": "listCatalogProducts", "summary": "List catalog products", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogProductsResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "One page; pass `nextCursor` back as `after` for the next.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta catalog id" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" } } ] }, "post": { "operationId": "writeCatalogProducts", "summary": "Upsert or delete catalog products", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CatalogBatchResult" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Up to 500 products in one batch, keyed by your own `retailerId`. Upserts and deletes travel together.\n\nRequires the `ads` and `publish` scopes when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta catalog id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogProductBatchRequest" } } } } } }, "/v1/ads/catalogs/{id}/feeds": { "get": { "operationId": "listProductFeeds", "summary": "List product feeds", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductFeed" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta catalog id" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ] }, "post": { "operationId": "createProductFeed", "summary": "Create a product feed", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProductFeed" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` and `publish` scopes when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta catalog id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProductFeedRequest" } } } } } }, "/v1/ads/catalogs/{id}/feeds/{feedId}": { "delete": { "operationId": "deleteProductFeed", "summary": "Delete a product feed", "tags": [ "Ads" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` and `publish` scopes when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta catalog id" }, { "name": "feedId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta product feed id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ] } }, "/v1/ads/catalogs/{id}/feeds/{feedId}/uploads": { "get": { "operationId": "listFeedUploads", "summary": "List feed uploads", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductFeedUpload" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Each run Meta made of the feed, newest first.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta catalog id" }, { "name": "feedId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta product feed id" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ] }, "post": { "operationId": "startFeedUpload", "summary": "Fetch a product feed now", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` and `publish` scopes when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta catalog id" }, { "name": "feedId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta product feed id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartFeedUploadRequest" } } } } } }, "/v1/ads/catalogs/{id}/product-sets": { "get": { "operationId": "listProductSets", "summary": "List product sets", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSet" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "A product set is what a catalog ad promotes.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta catalog id" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ] }, "post": { "operationId": "createProductSet", "summary": "Create a product set", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProductSet" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` and `publish` scopes when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta catalog id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductSetRequest" } } } } } }, "/v1/ads/catalogs/{id}/product-sets/{setId}": { "patch": { "operationId": "updateProductSet", "summary": "Rename or refilter a product set", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProductSet" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` and `publish` scopes when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta catalog id" }, { "name": "setId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta product set id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductSetRequest" } } } } }, "delete": { "operationId": "deleteProductSet", "summary": "Delete a product set", "tags": [ "Ads" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` and `publish` scopes when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta catalog id" }, { "name": "setId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta product set id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ] } }, "/v1/ads/reach-frequency": { "get": { "operationId": "listReachFrequency", "summary": "List reach and frequency predictions", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReachFrequencyResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" }, { "name": "ad_account_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "`act_…`" } ] }, "post": { "operationId": "createReachFrequency", "summary": "Predict reach and frequency", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ReachFrequencyPrediction" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "A prediction for a fixed flight and budget. Nothing is bought until you reserve it.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReachFrequencyRequest" } } } } } }, "/v1/ads/reach-frequency/{id}": { "get": { "operationId": "getReachFrequency", "summary": "Get a prediction", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ReachFrequencyPrediction" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta prediction id" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" }, { "name": "ad_account_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "`act_…`" } ] } }, "/v1/ads/reach-frequency/{id}/reserve": { "post": { "operationId": "reserveReachFrequency", "summary": "Reserve a prediction", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ReachFrequencyPrediction" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Holds the inventory the prediction priced. Spends on the ad account.\n\nRequires the `ads` and `publish` scopes when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta prediction id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReachFrequencyActionRequest" } } } } } }, "/v1/ads/reach-frequency/{id}/cancel": { "post": { "operationId": "cancelReachFrequency", "summary": "Cancel a reservation", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ReachFrequencyPrediction" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` and `publish` scopes when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta prediction id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReachFrequencyActionRequest" } } } } } }, "/v1/ads/library": { "get": { "operationId": "searchAdLibrary", "summary": "Search the public ad archive", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdLibraryResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Ads anyone is running, by keyword or by Page. Read live from Meta on every request and never stored, so a result that stops running is simply absent next time.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" }, { "name": "countries", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Comma-separated two-letter codes the ad reached" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Keyword; required unless `page_ids` is set" }, { "name": "page_ids", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated Page ids, up to 10" }, { "name": "active_status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "ALL" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "1–100, 25 by default" }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/v1/ads/partnership/creators": { "get": { "operationId": "listPartnershipCreators", "summary": "List allowlisted creators", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartnershipCreator" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Creators who allowlisted this Page to run partnership ads on their posts.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" }, { "name": "page_id", "in": "query", "required": true, "schema": { "type": "string" } } ] }, "post": { "operationId": "requestPartnership", "summary": "Ask a creator for partnership permission", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartnershipCreator" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnershipRequest" } } } } } }, "/v1/ads/partnership/creators/{creatorId}": { "delete": { "operationId": "revokePartnership", "summary": "Revoke a partnership permission", "tags": [ "Ads" ], "responses": { "204": { "description": "Revoked", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "creatorId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The creator's account id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" }, { "name": "page_id", "in": "query", "required": true, "schema": { "type": "string" } } ] } }, "/v1/ads/account/activity": { "get": { "operationId": "listAdAccountActivity", "summary": "List the ad account's activity log", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdActivityResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Every change Meta recorded on the ad account, read live and never stored.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" }, { "name": "ad_account_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "`act_…`" }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string" }, "description": "YYYY-MM-DD" }, { "name": "until", "in": "query", "required": false, "schema": { "type": "string" }, "description": "YYYY-MM-DD" } ] } }, "/v1/ads/account/labels": { "get": { "operationId": "listAdLabels", "summary": "List ad labels", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AdLabel" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" }, { "name": "ad_account_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "`act_…`" } ] }, "post": { "operationId": "createAdLabel", "summary": "Create an ad label", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdLabel" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdLabelRequest" } } } } } }, "/v1/ads/account/labels/{id}": { "patch": { "operationId": "updateAdLabel", "summary": "Rename an ad label", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdLabel" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta label id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdLabelRequest" } } } } }, "delete": { "operationId": "deleteAdLabel", "summary": "Delete an ad label", "tags": [ "Ads" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta label id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" }, { "name": "ad_account_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "`act_…`" } ] } }, "/v1/ads/account/labels/{id}/apply": { "post": { "operationId": "applyAdLabel", "summary": "Put a label on a campaign, ad set or ad", "tags": [ "Ads" ], "responses": { "204": { "description": "Applied", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Keeps whatever labels the object already carries.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta label id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyAdLabelRequest" } } } } } }, "/v1/ads/account/studies": { "get": { "operationId": "listAdStudies", "summary": "List A/B studies", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AdStudy" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" }, { "name": "ad_account_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "`act_…`" } ] }, "post": { "operationId": "createAdStudy", "summary": "Create an A/B study", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdStudy" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Splits traffic evenly across the cells for the length of the flight.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdStudyRequest" } } } } } }, "/v1/ads/account/studies/{id}": { "get": { "operationId": "getAdStudy", "summary": "Get an A/B study", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdStudy" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta study id" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" }, { "name": "ad_account_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "`act_…`" } ] }, "delete": { "operationId": "deleteAdStudy", "summary": "Delete an A/B study", "tags": [ "Ads" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta study id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" }, { "name": "ad_account_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "`act_…`" } ] } }, "/v1/ads/account/ios-limits": { "get": { "operationId": "listIosCampaignLimits", "summary": "List iOS 14 campaign limits", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IosCampaignLimits" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "How many iOS 14 campaigns the ad account may run at once, per app.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" }, { "name": "ad_account_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "`act_…`" } ] } }, "/v1/ads/account/high-demand-periods": { "get": { "operationId": "listHighDemandPeriods", "summary": "List high-demand periods", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/HighDemandPeriod" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" }, { "name": "ad_account_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "`act_…`" } ] }, "post": { "operationId": "createHighDemandPeriod", "summary": "Declare a high-demand period", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HighDemandPeriod" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Tells Meta to expect heavier spend over a window, so pacing allows for it.\n\nRequires the `ads` and `publish` scopes when using an API key.", "x-fopost-scope": "ads", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateHighDemandPeriodRequest" } } } } } }, "/v1/ads/account/high-demand-periods/{id}": { "delete": { "operationId": "deleteHighDemandPeriod", "summary": "Delete a high-demand period", "tags": [ "Ads" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` and `publish` scopes when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta high-demand period id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" }, { "name": "ad_account_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "`act_…`" } ] } }, "/v1/ads/account/value-rule-sets": { "get": { "operationId": "listValueRuleSets", "summary": "List value rule sets", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ValueRuleSet" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" }, { "name": "ad_account_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "`act_…`" } ] }, "post": { "operationId": "createValueRuleSet", "summary": "Create a value rule set", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ValueRuleSet" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Weights conversions so some audiences count for more than others.\n\nRequires the `ads` and `publish` scopes when using an API key.", "x-fopost-scope": "ads", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateValueRuleSetRequest" } } } } } }, "/v1/ads/account/value-rule-sets/{id}": { "delete": { "operationId": "deleteValueRuleSet", "summary": "Delete a value rule set", "tags": [ "Ads" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` and `publish` scopes when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta value rule set id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" }, { "name": "ad_account_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "`act_…`" } ] } }, "/v1/ads/audiences": { "get": { "operationId": "listAudiences", "summary": "List custom audiences and pixels", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudiencesResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "ad_account_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "`act_…`" } ] }, "post": { "operationId": "createAudience", "summary": "Create a custom audience", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "added": { "type": "integer", "description": "Emails accepted by Meta" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "A customer list (`CUSTOM`, emails are hashed before they leave), a lookalike of an existing audience (`LOOKALIKE`), or website visitors from a pixel (`WEBSITE`).\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAudienceRequest" } } } } } }, "/v1/ads/targeting/search": { "get": { "operationId": "searchTargeting", "summary": "Search the targeting catalogue", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TargetingOption" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Locations, interests, behaviours and income brackets as Meta names them, for the `targeting` block of an ad. `income` ignores `q`.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "country", "region", "city", "zip", "metro", "interest", "behavior", "income" ] } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 } } ] } }, "/v1/ads/lead-forms": { "get": { "operationId": "listLeadForms", "summary": "List Instant Forms", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LeadFormSource" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Every Page a Meta Ads connection reaches, with its lead forms.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] }, "post": { "operationId": "createLeadForm", "summary": "Create an Instant Form", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLeadFormRequest" } } } } } }, "/v1/ads/lead-forms/{formId}/leads": { "get": { "operationId": "listLeads", "summary": "List a form’s leads", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadsResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "One page of leads; pass `nextCursor` back as `after` for the next.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "formId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Instant Form id" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor from the previous page" } ] } }, "/v1/ads/{id}/insights": { "get": { "operationId": "getAdInsights", "summary": "Get an ad’s insights over a date range", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdInsightsReport" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "For an ad created through FoPost. Same report as `GET /v1/ads/insights`.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Ad id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "since", "in": "query", "required": true, "schema": { "type": "string" }, "description": "YYYY-MM-DD, inclusive" }, { "name": "until", "in": "query", "required": true, "schema": { "type": "string" }, "description": "YYYY-MM-DD, inclusive" }, { "name": "breakdown", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "age", "gender", "placement", "country" ] } }, { "name": "daily", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Add a day-by-day timeline" } ] } }, "/v1/ads/insights": { "get": { "operationId": "getInsights", "summary": "Get insights over a date range", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdInsightsReport" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Totals for an ad account (`act_…`), campaign, ad set or ad, optionally split by one breakdown and by day.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" }, { "name": "object_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "`act_…` or a Meta object id" }, { "name": "since", "in": "query", "required": true, "schema": { "type": "string" }, "description": "YYYY-MM-DD, inclusive" }, { "name": "until", "in": "query", "required": true, "schema": { "type": "string" }, "description": "YYYY-MM-DD, inclusive" }, { "name": "breakdown", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "age", "gender", "placement", "country" ] } }, { "name": "daily", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Add a day-by-day timeline" } ] } }, "/v1/ads/reach-estimate": { "post": { "operationId": "estimateReach", "summary": "Estimate audience size", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ReachEstimate" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "How many people the targeting reaches on the Page’s placements.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReachEstimateRequest" } } } } } }, "/v1/ads/tiktok/business-centers": { "get": { "operationId": "listTikTokBusinessCenters", "summary": "List TikTok Business Centers", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AdBusinessCenter" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "The ad network refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "TikTok groups ad accounts into Business Centers, which no other network has an equivalent for — hence the only network-named routes in this section. `unsupported` on any other connection.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ] } }, "/v1/ads/tiktok/identities": { "get": { "operationId": "listTikTokIdentities", "summary": "List TikTok identities", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AdIdentity" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "The ad network refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "The accounts an ad can run as on one ad account. An identity id is what a Spark ad and an ad group take as `pageId`.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" }, { "name": "ad_account_id", "in": "query", "required": true, "schema": { "type": "string" } } ] } }, "/v1/ads/spark-posts": { "get": { "operationId": "listSparkPosts", "summary": "List posts a Spark ad can promote", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SparkPost" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "The ad network refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Posts already live under an identity. Pass one as `platformPostId` on a creative to run it as an ad without re-uploading it. `unsupported` on a network without Spark ads.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" }, { "name": "ad_account_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "identity_id", "in": "query", "required": true, "schema": { "type": "string" } } ] } }, "/v1/ads/conversions": { "post": { "operationId": "uploadConversions", "summary": "Upload offline conversions", "tags": [ "Ads" ], "responses": { "202": { "description": "Accepted by the network", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "accepted": { "type": "integer" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "The ad network refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Events that happened away from the site, attributed to a pixel the ad account owns. Emails and phone numbers are hashed before anything leaves FoPost.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadConversionsRequest" } } } } } }, "/v1/ads/comments": { "get": { "operationId": "listAdComments", "summary": "List the comments on an ad", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdCommentsResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "The ad network refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Read live from the network and never stored. Paged through `nextCursor`.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" }, { "name": "ad_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The previous page’s `nextCursor`" } ] } }, "/v1/ads/comments/{id}/reply": { "post": { "operationId": "replyAdComment", "summary": "Reply to a comment on an ad", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "replyId": { "type": "string" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "The ad network refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Also requires the `publish` scope.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The comment id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyAdCommentRequest" } } } } } }, "/v1/ads/comments/{id}/hide": { "post": { "operationId": "hideAdComment", "summary": "Hide or show a comment on an ad", "tags": [ "Ads" ], "responses": { "204": { "description": "Hidden or shown", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "The ad network refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Also requires the `publish` scope.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The comment id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HideAdCommentRequest" } } } } } }, "/v1/ads/comments/{id}": { "delete": { "operationId": "deleteAdComment", "summary": "Delete a comment on an ad", "tags": [ "Ads" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "The ad network refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "A comment already gone on the network answers 204, not 404. Also requires the `publish` scope.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The comment id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteAdCommentRequest" } } } } } }, "/v1/ads/accounts/{adAccountId}/tree": { "get": { "operationId": "getAdAccountTree", "summary": "Get an ad account’s campaign tree", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdAccountTree" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Every campaign on the ad account with its ad sets and ads, whoever made them. Read live from Meta and never stored.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "adAccountId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "`act_…`" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ] } }, "/v1/ads/campaigns": { "post": { "operationId": "createAdCampaign", "summary": "Create a campaign", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdCampaign" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Starts paused unless `paused` is false. Also requires the `publish` scope.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdCampaignRequest" } } } } } }, "/v1/ads/campaigns/{id}": { "get": { "operationId": "getAdCampaign", "summary": "Get a campaign", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdCampaign" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta campaign id" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ] }, "patch": { "operationId": "updateAdCampaign", "summary": "Update a campaign", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdCampaign" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Setting `status` to `active` starts spend. Also requires the `publish` scope.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta campaign id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdCampaignRequest" } } } } }, "delete": { "operationId": "deleteAdCampaign", "summary": "Delete a campaign", "tags": [ "Ads" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Deletes it on Meta with everything beneath it. Also requires the `publish` scope.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta campaign id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ] } }, "/v1/ads/campaigns/{id}/duplicate": { "post": { "operationId": "duplicateAdCampaign", "summary": "Duplicate a campaign", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The copy's Meta id" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Copies it with everything beneath it. The copy starts paused unless `paused` is false. Also requires the `publish` scope.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta campaign id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicateAdObjectRequest" } } } } } }, "/v1/ads/ad-sets": { "post": { "operationId": "createAdSet", "summary": "Create an ad set", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdSet" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Under a campaign on an ad account the connection reaches. Starts paused unless `paused` is false. Also requires the `publish` scope.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdSetRequest" } } } } } }, "/v1/ads/ad-sets/{id}": { "get": { "operationId": "getAdSet", "summary": "Get an ad set", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdSet" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta ad set id" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ] }, "patch": { "operationId": "updateAdSet", "summary": "Update an ad set", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdSet" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Setting `status` to `active` starts spend. Also requires the `publish` scope.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta ad set id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdSetRequest" } } } } }, "delete": { "operationId": "deleteAdSet", "summary": "Delete an ad set", "tags": [ "Ads" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Deletes it on Meta with everything beneath it. Also requires the `publish` scope.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta ad set id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ] } }, "/v1/ads/ad-sets/{id}/duplicate": { "post": { "operationId": "duplicateAdSet", "summary": "Duplicate an ad set", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The copy's Meta id" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Copies it with everything beneath it. The copy starts paused unless `paused` is false. Also requires the `publish` scope.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta ad set id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicateAdObjectRequest" } } } } } }, "/v1/ads/ads": { "post": { "operationId": "createNetworkAd", "summary": "Create an ad in an ad set", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NetworkAd" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Joins an ad set and a creative. Starts paused unless `paused` is false. Also requires the `publish` scope.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNetworkAdRequest" } } } } } }, "/v1/ads/ads/{id}": { "get": { "operationId": "getNetworkAd", "summary": "Get an ad", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NetworkAd" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta ad id" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ] }, "patch": { "operationId": "updateNetworkAd", "summary": "Update an ad", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NetworkAd" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Setting `status` to `active` starts spend. Also requires the `publish` scope.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta ad id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNetworkAdRequest" } } } } }, "delete": { "operationId": "deleteNetworkAd", "summary": "Delete an ad", "tags": [ "Ads" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Deletes it on Meta with everything beneath it. Also requires the `publish` scope.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta ad id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ] } }, "/v1/ads/ads/{id}/duplicate": { "post": { "operationId": "duplicateNetworkAd", "summary": "Duplicate an ad", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The copy's Meta id" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Copies it with everything beneath it. The copy starts paused unless `paused` is false. Also requires the `publish` scope.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta ad id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicateAdObjectRequest" } } } } } }, "/v1/ads/status": { "post": { "operationId": "bulkSetAdStatus", "summary": "Pause or resume many objects", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BulkAdStatusResult" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Up to 50 campaigns, ad sets and ads. Each succeeds or fails on its own. Also requires the `publish` scope.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkAdStatusRequest" } } } } } }, "/v1/ads/creatives": { "get": { "operationId": "listAdCreatives", "summary": "List the creative library", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "creatives": { "type": "array", "items": { "$ref": "#/components/schemas/AdCreative" } }, "workspaceId": { "type": "string", "format": "uuid" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" }, { "name": "ad_account_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "`act_…`" } ] }, "post": { "operationId": "createAdCreative", "summary": "Create a creative", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdCreative" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "An image, video or carousel creative from library media. Nothing runs until an ad uses it.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdCreativeRequest" } } } } } }, "/v1/ads/creatives/{id}": { "get": { "operationId": "getAdCreative", "summary": "Get a creative", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdCreative" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta creative id" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ] }, "delete": { "operationId": "deleteAdCreative", "summary": "Delete a creative", "tags": [ "Ads" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta creative id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ] } }, "/v1/ads/audiences/{id}": { "get": { "operationId": "getAudience", "summary": "Get a custom audience", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Audience" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta audience id" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ] }, "patch": { "operationId": "updateAudience", "summary": "Rename or describe a custom audience", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Audience" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta audience id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAudienceRequest" } } } } }, "delete": { "operationId": "deleteAudience", "summary": "Delete a custom audience", "tags": [ "Ads" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta audience id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ] } }, "/v1/ads/audiences/{id}/users": { "post": { "operationId": "addAudienceUsers", "summary": "Add people to a customer-list audience", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "added": { "type": "integer", "description": "Emails sent to Meta" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meta audience id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddAudienceUsersRequest" } } } } } }, "/v1/ads/audiences/{id}/companies": { "post": { "operationId": "addAudienceCompanies", "summary": "Add companies to a company-list audience", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "added": { "type": "integer", "description": "Rows accepted by the network" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Business-to-business networks match on companies rather than people. The rows travel with the request and are never stored.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Audience id as the network addresses it" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddAudienceCompaniesRequest" } } } } } }, "/v1/ads/linkedin/bid-pricing": { "post": { "operationId": "getAdBidPricing", "summary": "Quote what an audience costs at auction", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BidPricing" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Named for the network that introduced it; any connection whose `capabilities.forecasts` is true answers it.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BidPricingRequest" } } } } } }, "/v1/ads/linkedin/supply-forecast": { "post": { "operationId": "getAdSupplyForecast", "summary": "Forecast what a budget would deliver", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SupplyForecast" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplyForecastRequest" } } } } } }, "/v1/ads/linkedin/conversion-rules": { "get": { "operationId": "listConversionRules", "summary": "List conversion rules on an ad account", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversionRule" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" }, { "name": "ad_account_id", "in": "query", "required": true, "schema": { "type": "string" } } ] }, "post": { "operationId": "createConversionRule", "summary": "Create a conversion rule", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConversionRuleRequest" } } } } } }, "/v1/ads/linkedin/conversion-rules/{id}": { "get": { "operationId": "getConversionRule", "summary": "Get a conversion rule", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ConversionRule" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Conversion rule id" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ] }, "patch": { "operationId": "updateConversionRule", "summary": "Change a conversion rule", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ConversionRule" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Conversion rule id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConversionRuleRequest" } } } } }, "delete": { "operationId": "deleteConversionRule", "summary": "Turn a conversion rule off", "tags": [ "Ads" ], "responses": { "204": { "description": "Turned off", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "The network keeps the history, so the rule stops counting rather than going away.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Conversion rule id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ] } }, "/v1/ads/linkedin/conversion-rules/{id}/associations": { "post": { "operationId": "attachConversionRule", "summary": "Attach a conversion rule to an ad set", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ConversionRule" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Conversion rule id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversionAssociationRequest" } } } } }, "delete": { "operationId": "detachConversionRule", "summary": "Detach a conversion rule from an ad set", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ConversionRule" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Conversion rule id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversionAssociationRequest" } } } } } }, "/v1/ads/linkedin/conversion-rules/{id}/metrics": { "get": { "operationId": "getConversionMetrics", "summary": "Read what a conversion rule recorded", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ConversionMetrics" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Conversion rule id" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" }, { "name": "since", "in": "query", "required": true, "schema": { "type": "string" }, "description": "YYYY-MM-DD" }, { "name": "until", "in": "query", "required": true, "schema": { "type": "string" }, "description": "YYYY-MM-DD" } ] } }, "/v1/ads/linkedin/conversion-rules/{id}/events": { "post": { "operationId": "sendConversionEvents", "summary": "Send conversions back to the network", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "accepted": { "type": "integer", "description": "Events the network took" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "The identity on each event is hashed inside the API; the address itself never reaches the network and nothing about an event is stored.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Conversion rule id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversionEventsRequest" } } } } } }, "/v1/ads/lead-forms/{formId}": { "get": { "operationId": "getLeadForm", "summary": "Get an Instant Form", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LeadFormDetail" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "formId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Instant Form id" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" }, { "name": "page_id", "in": "query", "required": true, "schema": { "type": "string" } } ] } }, "/v1/ads/lead-forms/{formId}/archive": { "post": { "operationId": "archiveLeadForm", "summary": "Archive an Instant Form", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LeadFormDetail" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "The form stops collecting; its leads stay readable.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "formId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Instant Form id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveLeadFormRequest" } } } } } }, "/v1/ads/leads": { "get": { "operationId": "listLeadsFeed", "summary": "List the leads feed", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "leads": { "type": "array", "items": { "$ref": "#/components/schemas/FeedLead" } }, "nextCursor": { "type": [ "string", "null" ] } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Every lead collected from subscribed Pages across the team, newest first. Pass `nextCursor` back as `cursor` for the next page.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "form_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "page_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ] } }, "/v1/ads/lead-pages": { "get": { "operationId": "listLeadPages", "summary": "List Pages feeding the leads feed", "tags": [ "Ads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LeadPage" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] }, "post": { "operationId": "subscribeLeadPage", "summary": "Collect a Page’s leads", "tags": [ "Ads" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "pageId": { "type": "string" }, "backfilled": { "type": "integer" } } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Meta refused the request; `message` carries its reason", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Turns on new-lead notifications for the Page and backfills its most recent leads into the feed.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscribeLeadPageRequest" } } } } } }, "/v1/ads/lead-pages/{pageId}": { "delete": { "operationId": "unsubscribeLeadPage", "summary": "Stop collecting a Page’s leads", "tags": [ "Ads" ], "responses": { "204": { "description": "Unsubscribed", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Leads already in the feed stay.\n\nRequires the `ads` scope when using an API key.", "x-fopost-scope": "ads", "parameters": [ { "name": "pageId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Facebook Page id" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The Meta Ads connection to act through" } ] } }, "/v1/media": { "get": { "operationId": "listMedia", "summary": "List media library items", "tags": [ "Media" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MediaLibraryItem" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Newest first. Without `workspace_id` the list spans every workspace the caller belongs to.\n\nRequires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Workspace to list media for" }, { "name": "folder_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Folder to list; `root` for unfiled assets" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Match the filename or a tag" }, { "name": "tag", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "image", "video", "gif", "document" ] } }, { "name": "url", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exact stored URL" }, { "name": "brand_role", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "logo", "product", "person", "background" ] } }, { "name": "brand_voice_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "generation_run_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "origin", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "shared", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "`true` lists only shared assets and adds each one's `share` link" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 60 } } ] } }, "/v1/media/upload": { "post": { "operationId": "uploadMedia", "summary": "Upload media files", "tags": [ "Media" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UploadedMedia" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "413": { "description": "A file is over the account ceiling or the 100 MB multipart ceiling (`file_too_large`, with `max_file_bytes`), or over the storage allowance (`storage_limit_reached`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Accepts up to 5 files as multipart/form-data under the `files` field, each within the account ceiling (`GET /v1/media/limits`) and the 100 MB this route carries; a larger file goes through direct upload. Allowed types: jpeg, png, gif, webp, mp4, mov, webm, pdf, txt, csv. File content is verified against the declared type. When `workspaceId` is provided the files are also saved to the media library.\n\nRequires the `posts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "posts", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "string", "format": "binary" } }, "workspaceId": { "type": "string", "format": "uuid" } }, "required": [ "files" ] } } } } } }, "/v1/media/limits": { "get": { "operationId": "getUploadLimits", "summary": "Upload limits", "tags": [ "Media" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadLimits" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "The largest file this account may upload and what set that ceiling, plus the per-file ceiling of a multipart request. Read it before uploading to pick the route and to tell the user the real limit.\n\nRequires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Resolve the ceiling for this workspace’s billing account" } ] } }, "/v1/media/presign": { "post": { "operationId": "presignMediaUpload", "summary": "Sign a direct upload", "tags": [ "Media" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresignedUpload" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "description": "The file is over the account ceiling (`file_too_large`, with `max_file_bytes`) or would exceed the storage allowance (`storage_limit_reached`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Direct upload is not set up on this deployment (`not_configured`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "description": "Returns a signed URL for one file up to the account ceiling (`GET /v1/media/limits`, at most 5 GB), same allowed types as upload. PUT the raw bytes to `upload_url` with exactly the returned headers and a `Content-Length` equal to `size`, then call the complete step. Nothing appears in the library until completion validates the object. An upload that is never completed is discarded after 24 hours.\n\nRequires the `posts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "posts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "filename": { "type": "string", "maxLength": 255 }, "mimeType": { "type": "string", "description": "One of: jpeg, png, gif, webp, mp4, mov, webm, pdf, txt, csv" }, "size": { "type": "integer", "minimum": 1, "maximum": 5368709120, "description": "Bytes" }, "folderId": { "type": "string", "format": "uuid", "description": "Library folder to file the item under" }, "origin": { "type": "string", "enum": [ "chat" ], "description": "Keep the file out of the library (chat attachment)" }, "brandRole": { "type": "string", "enum": [ "logo", "product", "person", "background" ] }, "brandVoiceId": { "type": "string", "format": "uuid" }, "personConsent": { "type": "object", "description": "Required with brandRole=person", "properties": { "subject": { "type": "string" }, "statement": { "type": "string" } } } }, "required": [ "workspaceId", "filename", "mimeType", "size" ] } } } } } }, "/v1/media/presign/{uploadId}/complete": { "post": { "operationId": "completeMediaUpload", "summary": "Complete a direct upload", "tags": [ "Media" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadedMedia" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Nothing was uploaded (`upload_missing`) or the content does not match the declared type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Already completed (`upload_already_completed`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "410": { "description": "The upload expired (`upload_expired`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "413": { "description": "The object is over the account ceiling (`file_too_large`) or would exceed the storage allowance (`storage_limit_reached`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Validates the object that was PUT to the signed URL (type, content, size, storage allowance) exactly like an upload and moves it into the media library. A refused object is deleted. Answers `409` if already completed and `410` once expired.\n\nRequires the `posts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-fopost-scope": "posts", "parameters": [ { "name": "uploadId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Upload id from the presign step" } ] } }, "/v1/media/{id}": { "delete": { "operationId": "deleteMedia", "summary": "Delete a media item", "tags": [ "Media" ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Removes the stored file and the media library record.\n\nRequires the `posts` scope when using an API key.", "x-fopost-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Media library id" } ] } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key created in the FoPost dashboard. A key may be bound to a single workspace, in which case every request is confined to it: naming any other workspace returns 403, and listings return only that workspace. Keys created without a workspace keep access to every workspace on the account." }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Session token used by the FoPost dashboard" }, "OAuth2": { "type": "oauth2", "description": "For third-party apps acting on behalf of a FoPost user. Authorization code with PKCE (S256) is required. The token is confined to the workspace the user approved and to the scopes they granted.", "flows": { "authorizationCode": { "authorizationUrl": "https://api.fopost.com/oauth/authorize", "tokenUrl": "https://api.fopost.com/oauth/token", "refreshUrl": "https://api.fopost.com/oauth/token", "scopes": { "posts": "Read and write posts, media and content", "publish": "Publish, retry and cancel a post", "accounts": "Connected social accounts", "workspaces": "List and manage workspaces", "labels": "Labels used to organise posts", "webhooks": "Webhook endpoints", "analytics": "Metrics and insights", "automations": "Automation rules and runs", "inbox": "Comments, mentions and messages", "ads": "Meta ads, audiences and lead forms", "ai": "AI features (spends credits)", "extension": "Reserved for the browser extension" } } } } }, "schemas": { "CreateConnectSessionRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "externalUserId": { "type": "string", "minLength": 1, "maxLength": 255 }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "twitter", "instagram", "linkedin", "threads", "tiktok", "youtube", "reddit", "tumblr", "dribbble" ] }, "minItems": 1, "maxItems": 9 }, "redirectUrl": { "type": "string", "maxLength": 2048, "format": "uri" }, "branding": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "logoUrl": { "type": "string", "maxLength": 2048, "format": "uri" } } } }, "required": [ "externalUserId", "platforms" ] }, "CreatePostRequest": { "type": "object", "properties": { "workspace_id": { "type": "string", "format": "uuid" }, "accounts": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [] }, "account_group_id": { "type": "string", "format": "uuid" }, "content": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": [ "string", "null" ] }, "media": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video", "gif" ] }, "name": { "type": "string", "minLength": 1 }, "url": { "type": "string", "format": "uri" }, "size": { "type": "number", "exclusiveMinimum": 0 }, "alt": { "type": "string" }, "thumbnail": { "type": "string", "format": "uri" } }, "required": [ "type", "name", "url" ] } } } }, "minItems": 1 }, "content_type": { "type": "string", "enum": [ "post", "thread", "reel" ], "default": "post" }, "artifact_type": { "type": "string", "enum": [ "text_post", "thread", "article", "carousel", "short_video", "story", "link_share" ], "default": "text_post" }, "status": { "type": "string", "enum": [ "draft", "scheduled" ], "default": "draft" }, "schedule_at": { "type": [ "string", "null" ], "format": "date-time" }, "schedule": { "type": "string", "enum": [ "queue" ] }, "repeatable": { "type": "boolean", "default": false }, "repeatable_times": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "repeatable_gap": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "repeatable_gap_unit": { "type": [ "string", "null" ], "enum": [ "hours", "days", "weeks", "months" ] }, "labels": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "title": { "type": [ "string", "null" ], "maxLength": 255 }, "internal_title": { "type": [ "string", "null" ], "maxLength": 255 }, "summary": { "type": [ "string", "null" ], "maxLength": 500 }, "auto_plug": { "type": "boolean", "default": false }, "auto_plug_content": { "type": [ "string", "null" ], "maxLength": 500 }, "settings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": {} } }, "source_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 5 }, "companion_of": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "workspace_id", "content" ] }, "UpdatePostRequest": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 }, "content": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": [ "string", "null" ] }, "media": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video", "gif" ] }, "name": { "type": "string", "minLength": 1 }, "url": { "type": "string", "format": "uri" }, "size": { "type": "number", "exclusiveMinimum": 0 }, "alt": { "type": "string" }, "thumbnail": { "type": "string", "format": "uri" } }, "required": [ "type", "name", "url" ] } } } }, "minItems": 1 }, "content_type": { "type": "string", "enum": [ "post", "thread", "reel" ] }, "artifact_type": { "type": "string", "enum": [ "text_post", "thread", "article", "carousel", "short_video", "story", "link_share" ] }, "status": { "type": "string", "enum": [ "draft", "scheduled" ] }, "schedule_at": { "type": [ "string", "null" ], "format": "date-time" }, "schedule": { "type": "string", "enum": [ "queue" ] }, "repeatable": { "type": "boolean" }, "repeatable_times": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "repeatable_gap": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "repeatable_gap_unit": { "type": [ "string", "null" ], "enum": [ "hours", "days", "weeks", "months" ] }, "labels": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "title": { "type": [ "string", "null" ], "maxLength": 255 }, "internal_title": { "type": [ "string", "null" ], "maxLength": 255 }, "summary": { "type": [ "string", "null" ], "maxLength": 500 }, "auto_plug": { "type": "boolean" }, "auto_plug_content": { "type": [ "string", "null" ], "maxLength": 500 }, "settings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": {} } } } }, "PublishPostRequest": { "type": "object", "properties": { "accountIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 }, "options": { "type": "object", "properties": { "dryRun": { "type": "boolean" } } } } }, "RetryPostRequest": { "type": "object", "properties": { "accountIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "includePublished": { "type": "boolean" } } }, "CancelPostRequest": { "type": "object", "properties": { "accountIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "ValidatePostRequest": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 50000, "default": "", "description": "The post text" }, "media": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "mime_type": { "type": "string", "minLength": 1, "maxLength": 100, "description": "MIME type of the file" }, "size": { "type": "integer", "exclusiveMinimum": 0, "description": "File size in bytes" } }, "required": [ "url", "mime_type" ] }, "maxItems": 20, "default": [] }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "twitter", "instagram", "instagram-business", "facebook", "linkedin", "linkedin-page", "tiktok", "youtube", "bluesky", "threads", "mastodon", "lemmy", "pinterest", "snapchat", "telegram", "twitch", "discord", "slack", "reddit", "tumblr", "dribbble", "mewe", "devto", "hashnode", "medium", "substack", "google-business", "kick", "listmonk", "wordpress", "nostr", "whop", "skool" ] }, "minItems": 1, "description": "Platforms to check the content against" } }, "required": [ "platforms" ] }, "ValidateLengthRequest": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 50000 }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "twitter", "instagram", "instagram-business", "facebook", "linkedin", "linkedin-page", "tiktok", "youtube", "bluesky", "threads", "mastodon", "lemmy", "pinterest", "snapchat", "telegram", "twitch", "discord", "slack", "reddit", "tumblr", "dribbble", "mewe", "devto", "hashnode", "medium", "substack", "google-business", "kick", "listmonk", "wordpress", "nostr", "whop", "skool" ] }, "minItems": 1, "description": "Platforms to check the content against" } }, "required": [ "text", "platforms" ] }, "ValidateMediaRequest": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Public http(s) URL of the file to check" } }, "required": [ "url" ] }, "CreateQueueSlotRequest": { "type": "object", "properties": { "workspace_id": { "type": "string", "format": "uuid" }, "account_id": { "type": [ "string", "null" ], "format": "uuid" }, "weekday": { "type": "integer", "minimum": 0, "maximum": 6 }, "time": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "workspace_id", "weekday", "time", "timezone" ] }, "UpdateQueueSlotRequest": { "type": "object", "properties": { "account_id": { "type": [ "string", "null" ], "format": "uuid" }, "weekday": { "type": "integer", "minimum": 0, "maximum": 6 }, "time": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "CreateAccountRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "twitter", "instagram", "instagram-business", "facebook", "linkedin", "linkedin-page", "tiktok", "youtube", "bluesky", "threads", "mastodon", "lemmy", "pinterest", "snapchat", "telegram", "twitch", "discord", "slack", "reddit", "tumblr", "dribbble", "mewe", "devto", "hashnode", "medium", "substack", "google-business", "kick", "listmonk", "wordpress", "nostr", "whop", "skool" ] }, "username": { "type": "string", "minLength": 1, "maxLength": 255 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "avatar": { "type": [ "string", "null" ], "maxLength": 500 }, "credentials": { "type": "object", "additionalProperties": {} } }, "required": [ "workspaceId", "platform", "username", "name" ] }, "SetTelegramBotCommandsRequest": { "type": "object", "properties": { "commands": { "type": "array", "items": { "type": "object", "properties": { "command": { "type": "string", "pattern": "^[a-z0-9_]{1,32}$" }, "description": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "command", "description" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 } }, "required": [ "commands" ], "additionalProperties": false }, "SetIceBreakersRequest": { "type": "object", "properties": { "ice_breakers": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string", "minLength": 1, "maxLength": 80 }, "payload": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": [ "question", "payload" ], "additionalProperties": false }, "minItems": 1, "maxItems": 4 } }, "required": [ "ice_breakers" ], "additionalProperties": false }, "SetPersistentMenuRequest": { "type": "object", "properties": { "persistent_menu": { "type": "array", "items": { "type": "object", "properties": { "call_to_actions": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "postback" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 30 }, "payload": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": [ "type", "title", "payload" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "web_url" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 30 }, "url": { "type": "string", "maxLength": 2048, "format": "uri" } }, "required": [ "type", "title", "url" ], "additionalProperties": false } ] }, "minItems": 1, "maxItems": 3 }, "locale": { "type": "string", "minLength": 2, "maxLength": 10, "default": "default" }, "composer_input_disabled": { "type": "boolean" } }, "required": [ "call_to_actions" ], "additionalProperties": false }, "minItems": 1, "maxItems": 10 } }, "required": [ "persistent_menu" ], "additionalProperties": false }, "SetGreetingRequest": { "type": "object", "properties": { "greeting": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "minLength": 2, "maxLength": 10, "default": "default" }, "text": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "text" ], "additionalProperties": false }, "minItems": 1, "maxItems": 10 } }, "required": [ "greeting" ], "additionalProperties": false }, "InboxHandoverRequest": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1 }, "app_id": { "type": "string", "pattern": "^\\d{1,32}$" }, "metadata": { "type": "string", "maxLength": 1000 } }, "required": [ "account_id" ], "additionalProperties": false }, "CreateWorkspaceRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "type": { "type": "string", "enum": [ "PERSONAL", "TEAM", "ORGANIZATION", "CLIENT", "PROJECT", "DEPARTMENT", "EVENT", "TEMPORARY", "COMMUNITY", "BRAND", "AGENCY" ], "default": "PERSONAL" }, "logo": { "type": [ "string", "null" ], "maxLength": 500 }, "website": { "type": [ "string", "null" ], "maxLength": 500 }, "timezone": { "type": "string", "maxLength": 100, "default": "UTC" }, "country": { "type": [ "string", "null" ], "maxLength": 100 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "language": { "type": "string", "maxLength": 10, "default": "en" } }, "required": [ "name" ] }, "UpdateWorkspaceRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "type": { "type": "string", "enum": [ "PERSONAL", "TEAM", "ORGANIZATION", "CLIENT", "PROJECT", "DEPARTMENT", "EVENT", "TEMPORARY", "COMMUNITY", "BRAND", "AGENCY" ] }, "logo": { "type": [ "string", "null" ], "maxLength": 500 }, "website": { "type": [ "string", "null" ], "maxLength": 500 }, "timezone": { "type": "string", "maxLength": 100 }, "country": { "type": [ "string", "null" ], "maxLength": 100 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "language": { "type": "string", "maxLength": 10 }, "requireApproval": { "type": "boolean" }, "aiAltTextEnabled": { "type": "boolean" }, "brandColor": { "type": [ "string", "null" ], "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$" }, "connectRedirectDomains": { "type": "array", "items": { "type": "string", "pattern": "^(?=.{1,253}$)(?!-)[a-z0-9-]+(?\"'`]*$", "description": "Query string appended to every link in the ad, e.g. `utm_source=meta&utm_medium=paid`" }, "messagingDestination": { "type": "string", "enum": [ "messenger", "instagram_direct", "whatsapp" ], "description": "Required by the `messages` goal. `whatsapp` is refused unless the deployment has a WhatsApp business number" }, "phoneNumber": { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$", "description": "Required by the `calls` goal, in E.164, e.g. `+14155550123`" }, "productSetId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Required by the `sales` goal: makes this a catalog ad over that product set" } }, "required": [ "workspaceId", "connectionId", "adAccountId", "name", "goal", "budget", "targeting", "pageId" ] }, "SetAdStatusRequest": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "paused" ] } }, "required": [ "status" ] }, "CreateAudienceRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "connectionId": { "type": "string", "format": "uuid" }, "adAccountId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Ad account id as the network addresses it: `act_…` on Meta, `urn:li:sponsoredAccount:…` on LinkedIn" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 500 }, "spec": { "oneOf": [ { "type": "object", "properties": { "subtype": { "type": "string", "enum": [ "CUSTOM" ] }, "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 10000, "default": [], "description": "Customer list; hashed before it leaves the API" } }, "required": [ "subtype" ] }, { "type": "object", "properties": { "subtype": { "type": "string", "enum": [ "LOOKALIKE" ] }, "originAudienceId": { "type": "string", "minLength": 1, "maxLength": 64 }, "country": { "type": "string", "minLength": 2, "maxLength": 2 }, "ratio": { "type": "number", "minimum": 0.01, "maximum": 0.2, "default": 0.01 } }, "required": [ "subtype", "originAudienceId", "country" ] }, { "type": "object", "properties": { "subtype": { "type": "string", "enum": [ "WEBSITE" ] }, "pixelId": { "type": "string", "minLength": 1, "maxLength": 64 }, "retentionDays": { "type": "integer", "minimum": 1, "maximum": 180, "default": 30 }, "urlContains": { "type": "string", "maxLength": 255 } }, "required": [ "subtype", "pixelId" ] }, { "type": "object", "properties": { "subtype": { "type": "string", "enum": [ "COMPANY_LIST" ] }, "companies": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "domain": { "type": "string", "maxLength": 255 }, "pageUrl": { "type": "string", "maxLength": 2048, "format": "uri" }, "ticker": { "type": "string", "maxLength": 10 }, "country": { "type": "string", "minLength": 2, "maxLength": 2 } } }, "maxItems": 10000, "default": [], "description": "Company list; the rows travel with the request and are never stored" } }, "required": [ "subtype" ] }, { "type": "object", "properties": { "subtype": { "type": "string", "enum": [ "ENGAGEMENT" ] }, "source": { "type": "string", "enum": [ "page", "ad", "lead_form", "video" ] }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 64 }, "retentionDays": { "type": "integer", "minimum": 1, "maximum": 365, "default": 90 } }, "required": [ "subtype", "source", "sourceId" ] } ] } }, "required": [ "workspaceId", "connectionId", "adAccountId", "name", "spec" ] }, "AddAudienceCompaniesRequest": { "type": "object", "properties": { "companies": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "domain": { "type": "string", "maxLength": 255 }, "pageUrl": { "type": "string", "maxLength": 2048, "format": "uri" }, "ticker": { "type": "string", "maxLength": 10 }, "country": { "type": "string", "minLength": 2, "maxLength": 2 } } }, "minItems": 1, "maxItems": 10000 } }, "required": [ "companies" ] }, "BidPricingRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "connectionId": { "type": "string", "format": "uuid" }, "adAccountId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Ad account id as the network addresses it: `act_…` on Meta, `urn:li:sponsoredAccount:…` on LinkedIn" }, "goal": { "type": "string", "enum": [ "engagement", "traffic", "awareness", "video_views", "messages", "calls", "whatsapp", "sales" ] }, "targeting": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2 }, "maxItems": 50, "description": "ISO 3166-1 alpha-2 codes. At least one country or one location is required." }, "ageMin": { "type": "integer", "minimum": 13, "maximum": 65 }, "ageMax": { "type": "integer", "minimum": 13, "maximum": 65 }, "gender": { "type": "string", "enum": [ "all", "male", "female" ] }, "audienceIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 20 }, "locations": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "type": { "type": "string", "enum": [ "region", "city", "zip", "geo_market" ] } }, "required": [ "key", "name", "type" ] }, "maxItems": 200, "description": "Locations below country level, from `GET /v1/ads/targeting/search`" }, "interests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "id", "name" ] }, "maxItems": 100 }, "behaviors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "id", "name" ] }, "maxItems": 100 }, "income": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "id", "name" ] }, "maxItems": 10 }, "facets": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "id", "name" ] }, "maxItems": 100 }, "description": "Facets the network defines for itself, keyed by the type used with `GET /v1/ads/targeting/search` — `job_title`, `company_size`, `industry` and the rest of the B2B set on LinkedIn." } }, "required": [ "countries", "ageMin", "ageMax", "gender" ] }, "placements": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 10 }, "bidType": { "type": "string", "enum": [ "CPC", "CPM", "CPV" ] } }, "required": [ "workspaceId", "connectionId", "adAccountId", "goal", "targeting" ] }, "SupplyForecastRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "connectionId": { "type": "string", "format": "uuid" }, "adAccountId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Ad account id as the network addresses it: `act_…` on Meta, `urn:li:sponsoredAccount:…` on LinkedIn" }, "goal": { "type": "string", "enum": [ "engagement", "traffic", "awareness", "video_views", "messages", "calls", "whatsapp", "sales" ] }, "targeting": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2 }, "maxItems": 50, "description": "ISO 3166-1 alpha-2 codes. At least one country or one location is required." }, "ageMin": { "type": "integer", "minimum": 13, "maximum": 65 }, "ageMax": { "type": "integer", "minimum": 13, "maximum": 65 }, "gender": { "type": "string", "enum": [ "all", "male", "female" ] }, "audienceIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 20 }, "locations": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "type": { "type": "string", "enum": [ "region", "city", "zip", "geo_market" ] } }, "required": [ "key", "name", "type" ] }, "maxItems": 200, "description": "Locations below country level, from `GET /v1/ads/targeting/search`" }, "interests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "id", "name" ] }, "maxItems": 100 }, "behaviors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "id", "name" ] }, "maxItems": 100 }, "income": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "id", "name" ] }, "maxItems": 10 }, "facets": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "id", "name" ] }, "maxItems": 100 }, "description": "Facets the network defines for itself, keyed by the type used with `GET /v1/ads/targeting/search` — `job_title`, `company_size`, `industry` and the rest of the B2B set on LinkedIn." } }, "required": [ "countries", "ageMin", "ageMax", "gender" ] }, "placements": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 10 }, "budgetMinor": { "type": "integer", "minimum": 1, "maximum": 100000000, "description": "Budget for the forecast window, ad account currency, minor units" } }, "required": [ "workspaceId", "connectionId", "adAccountId", "goal", "targeting" ] }, "CreateConversionRuleRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "connectionId": { "type": "string", "format": "uuid" }, "adAccountId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Ad account id as the network addresses it: `act_…` on Meta, `urn:li:sponsoredAccount:…` on LinkedIn" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "type": { "type": "string", "enum": [ "purchase", "lead", "sign_up", "add_to_cart", "download", "install", "key_page_view", "other" ] }, "attribution": { "type": "string", "enum": [ "last_touch", "each_campaign" ] }, "postClickWindowDays": { "type": "integer", "minimum": 1, "maximum": 90, "default": 30 }, "viewThroughWindowDays": { "type": "integer", "minimum": 1, "maximum": 90, "default": 7 }, "valueMinor": { "type": "integer", "minimum": 0, "maximum": 100000000, "description": "Default value of one conversion, ad account currency, minor units" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "workspaceId", "connectionId", "adAccountId", "name", "type", "attribution" ] }, "UpdateConversionRuleRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "type": { "type": "string", "enum": [ "purchase", "lead", "sign_up", "add_to_cart", "download", "install", "key_page_view", "other" ] }, "attribution": { "type": "string", "enum": [ "last_touch", "each_campaign" ] }, "postClickWindowDays": { "type": "integer", "minimum": 1, "maximum": 90 }, "viewThroughWindowDays": { "type": "integer", "minimum": 1, "maximum": 90 }, "valueMinor": { "type": "integer", "minimum": 0, "maximum": 100000000, "description": "Default value of one conversion, ad account currency, minor units" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "enabled": { "type": "boolean" } } }, "ConversionAssociationRequest": { "type": "object", "properties": { "campaignId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "An ad set on the same connection" } }, "required": [ "campaignId" ] }, "ConversionEventsRequest": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "happenedAt": { "type": "integer", "minimum": 0, "description": "Epoch milliseconds" }, "valueMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Your own id for the event, so a replay is deduplicated" }, "email": { "type": "string", "format": "email", "description": "Hashed inside the API; the address itself never reaches the network" }, "clickId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The network click id, as the landing page received it" } }, "required": [ "happenedAt" ] }, "minItems": 1, "maxItems": 100, "description": "Each event needs an email address or a click id" } }, "required": [ "events" ] }, "CreateLeadFormRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "connectionId": { "type": "string", "format": "uuid" }, "pageId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Facebook Page id on Meta, `urn:li:organization:…` on LinkedIn" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "questions": { "type": "array", "items": { "type": "string", "enum": [ "EMAIL", "FULL_NAME", "PHONE" ] }, "minItems": 1, "maxItems": 3 }, "privacyPolicyUrl": { "type": "string", "maxLength": 2048, "format": "uri" }, "thankYouMessage": { "type": "string", "minLength": 1, "maxLength": 500 }, "followUpUrl": { "type": "string", "maxLength": 2048, "format": "uri" } }, "required": [ "workspaceId", "connectionId", "pageId", "name", "questions", "privacyPolicyUrl", "thankYouMessage" ] }, "ConnectMetaAdsRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "method": { "type": "string", "enum": [ "business", "user" ], "default": "business", "description": "`business` for Facebook Login for Business, `user` for a personal login" }, "returnTo": { "type": "string", "maxLength": 200, "pattern": "^\\/[A-Za-z0-9/_-]*(\\?[A-Za-z0-9=&_-]*)?$", "description": "Dashboard path to land on after Meta redirects back" } }, "required": [ "workspaceId" ] }, "CreateGoogleKeywordRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "connectionId": { "type": "string", "format": "uuid" }, "customerId": { "type": "string", "pattern": "^\\d{8,12}$", "description": "Google Ads customer id, digits only" }, "adGroupId": { "type": "string", "pattern": "^\\d{8,12}~[a-zA-Z]+~\\d{1,20}(~\\d{1,20})?$", "description": "`~~`, e.g. `1234567890~adGroup~77`" }, "text": { "type": "string", "minLength": 1, "maxLength": 80 }, "matchType": { "type": "string", "enum": [ "EXACT", "PHRASE", "BROAD" ] }, "cpcBidMinor": { "type": "integer", "exclusiveMinimum": 0, "description": "Bid in account minor units" } }, "required": [ "workspaceId", "connectionId", "customerId", "adGroupId", "text", "matchType" ] }, "UpdateGoogleKeywordRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "connectionId": { "type": "string", "format": "uuid" }, "customerId": { "type": "string", "pattern": "^\\d{8,12}$", "description": "Google Ads customer id, digits only" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "cpcBidMinor": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "workspaceId", "connectionId", "customerId" ] }, "GoogleAdsScopeRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "connectionId": { "type": "string", "format": "uuid" }, "customerId": { "type": "string", "pattern": "^\\d{8,12}$", "description": "Google Ads customer id, digits only" } }, "required": [ "workspaceId", "connectionId", "customerId" ] }, "GoogleKeywordIdeasRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "connectionId": { "type": "string", "format": "uuid" }, "customerId": { "type": "string", "pattern": "^\\d{8,12}$", "description": "Google Ads customer id, digits only" }, "seeds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "maxItems": 20 }, "url": { "type": "string", "format": "uri" }, "languageId": { "type": "string" }, "geoTargetIds": { "type": "array", "items": { "type": "string" }, "maxItems": 10 } }, "required": [ "workspaceId", "connectionId", "customerId" ] }, "CreateGoogleAssetRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "connectionId": { "type": "string", "format": "uuid" }, "customerId": { "type": "string", "pattern": "^\\d{8,12}$", "description": "Google Ads customer id, digits only" }, "spec": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "sitelink" ] }, "text": { "type": "string", "minLength": 1, "maxLength": 25 }, "description1": { "type": "string", "maxLength": 35 }, "description2": { "type": "string", "maxLength": 35 }, "finalUrl": { "type": "string", "format": "uri" } }, "required": [ "kind", "text", "finalUrl" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "callout" ] }, "text": { "type": "string", "minLength": 1, "maxLength": 25 } }, "required": [ "kind", "text" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "snippet" ] }, "header": { "type": "string", "minLength": 1, "maxLength": 25 }, "values": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 25 }, "minItems": 3, "maxItems": 10 } }, "required": [ "kind", "header", "values" ] } ] } }, "required": [ "workspaceId", "connectionId", "customerId", "spec" ] }, "CreateGoogleAssetGroupRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "connectionId": { "type": "string", "format": "uuid" }, "customerId": { "type": "string", "pattern": "^\\d{8,12}$", "description": "Google Ads customer id, digits only" }, "campaignId": { "type": "string", "pattern": "^\\d{8,12}~[a-zA-Z]+~\\d{1,20}(~\\d{1,20})?$", "description": "`~~`, e.g. `1234567890~adGroup~77`" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "finalUrls": { "type": "array", "items": { "type": "string", "format": "uri" }, "minItems": 1, "maxItems": 10 }, "status": { "type": "string", "enum": [ "active", "paused" ], "default": "paused" } }, "required": [ "workspaceId", "connectionId", "customerId", "campaignId", "name", "finalUrls" ] }, "UploadGoogleConversionsRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "connectionId": { "type": "string", "format": "uuid" }, "customerId": { "type": "string", "pattern": "^\\d{8,12}$", "description": "Google Ads customer id, digits only" }, "conversions": { "type": "array", "items": { "type": "object", "properties": { "gclid": { "type": "string" }, "gbraid": { "type": "string" }, "wbraid": { "type": "string" }, "conversionActionId": { "type": "string" }, "conversionDateTime": { "type": "string", "description": "`yyyy-MM-dd HH:mm:ss+|-HH:mm`, the only shape Google accepts" }, "valueMinor": { "type": "integer", "minimum": 0 }, "currencyCode": { "type": "string", "minLength": 3, "maxLength": 3 }, "orderId": { "type": "string", "maxLength": 128 } }, "required": [ "conversionActionId", "conversionDateTime" ] }, "minItems": 1, "maxItems": 200 } }, "required": [ "workspaceId", "connectionId", "customerId", "conversions" ] }, "GoogleInsightsQueryRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "connectionId": { "type": "string", "format": "uuid" }, "customerId": { "type": "string", "pattern": "^\\d{8,12}$", "description": "Google Ads customer id, digits only" }, "query": { "type": "string", "minLength": 10, "maxLength": 5000, "description": "A read-only GAQL SELECT" } }, "required": [ "connectionId", "customerId", "query" ] }, "UploadConversionsRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "connectionId": { "type": "string", "format": "uuid", "description": "A Meta Ads connection in the workspace" }, "adAccountId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Ad account id as the network addresses it: `act_…` on Meta, `urn:li:sponsoredAccount:…` on LinkedIn" }, "pixelId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "From `GET /v1/ads/audiences`" }, "events": { "type": "array", "items": { "type": "object", "properties": { "eventName": { "type": "string", "minLength": 1, "maxLength": 64 }, "occurredAt": { "type": [ "string", "null" ] }, "email": { "type": "string", "format": "email", "description": "Hashed before it leaves FoPost" }, "phone": { "type": "string", "minLength": 3, "maxLength": 32, "description": "Hashed before it leaves FoPost" }, "valueMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "orderId": { "type": "string", "maxLength": 128 } }, "required": [ "eventName", "occurredAt" ] }, "minItems": 1, "maxItems": 1000 } }, "required": [ "workspaceId", "connectionId", "adAccountId", "pixelId", "events" ] }, "ReplyAdCommentRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "connectionId": { "type": "string", "format": "uuid", "description": "A Meta Ads connection in the workspace" }, "adId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Meta object id" }, "text": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "workspaceId", "connectionId", "adId", "text" ] }, "HideAdCommentRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "connectionId": { "type": "string", "format": "uuid", "description": "A Meta Ads connection in the workspace" }, "adId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Meta object id" }, "hidden": { "type": "boolean" } }, "required": [ "workspaceId", "connectionId", "adId", "hidden" ] }, "DeleteAdCommentRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "connectionId": { "type": "string", "format": "uuid", "description": "A Meta Ads connection in the workspace" }, "adId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Meta object id" } }, "required": [ "workspaceId", "connectionId", "adId" ] }, "CreateAdCampaignRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "connectionId": { "type": "string", "format": "uuid", "description": "A Meta Ads connection in the workspace" }, "adAccountId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Ad account id as the network addresses it: `act_…` on Meta, `urn:li:sponsoredAccount:…` on LinkedIn" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "goal": { "type": "string", "enum": [ "engagement", "traffic", "awareness", "video_views", "messages", "calls", "whatsapp", "sales" ] }, "paused": { "type": "boolean", "default": true, "description": "Create it paused; set to false to go live at once" }, "smartPlus": { "type": "boolean", "default": false, "description": "Hands targeting and creative rotation to the network. Only on a network whose `capabilities.smartPlus` is true; 400 otherwise." } }, "required": [ "workspaceId", "connectionId", "adAccountId", "name", "goal" ] }, "UpdateAdCampaignRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "status": { "type": "string", "enum": [ "active", "paused" ] } } }, "CreateAdSetRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "connectionId": { "type": "string", "format": "uuid", "description": "A Meta Ads connection in the workspace" }, "campaignId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Meta object id" }, "pageId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The Page the ads in this set run as" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "goal": { "type": "string", "enum": [ "engagement", "traffic", "awareness", "video_views", "messages", "calls", "whatsapp", "sales" ] }, "budget": { "type": "object", "properties": { "minor": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100000000, "description": "Amount in the ad account currency, minor units" }, "type": { "type": "string", "enum": [ "daily", "lifetime" ] }, "endAt": { "type": "string", "format": "date-time" } }, "required": [ "minor", "type" ] }, "targeting": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2 }, "maxItems": 50, "description": "ISO 3166-1 alpha-2 codes. At least one country or one location is required." }, "ageMin": { "type": "integer", "minimum": 13, "maximum": 65 }, "ageMax": { "type": "integer", "minimum": 13, "maximum": 65 }, "gender": { "type": "string", "enum": [ "all", "male", "female" ] }, "audienceIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 20 }, "locations": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "type": { "type": "string", "enum": [ "region", "city", "zip", "geo_market" ] } }, "required": [ "key", "name", "type" ] }, "maxItems": 200, "description": "Locations below country level, from `GET /v1/ads/targeting/search`" }, "interests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "id", "name" ] }, "maxItems": 100 }, "behaviors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "id", "name" ] }, "maxItems": 100 }, "income": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "id", "name" ] }, "maxItems": 10 }, "facets": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "id", "name" ] }, "maxItems": 100 }, "description": "Facets the network defines for itself, keyed by the type used with `GET /v1/ads/targeting/search` — `job_title`, `company_size`, `industry` and the rest of the B2B set on LinkedIn." } }, "required": [ "countries", "ageMin", "ageMax", "gender" ] }, "paused": { "type": "boolean", "default": true, "description": "Create it paused; set to false to go live at once" }, "messagingDestination": { "type": "string", "enum": [ "messenger", "instagram_direct", "whatsapp" ], "description": "Required by the `messages` goal. `whatsapp` is refused unless the deployment has a WhatsApp business number" }, "phoneNumber": { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$", "description": "Required by the `calls` goal, in E.164, e.g. `+14155550123`" }, "productSetId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Required by the `sales` goal: makes this a catalog ad over that product set" } }, "required": [ "workspaceId", "connectionId", "campaignId", "pageId", "name", "goal", "budget", "targeting" ] }, "UpdateAdSetRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "budgetMinor": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100000000, "description": "New budget in minor units; the budget type set at creation stays" }, "endAt": { "type": "string", "format": "date-time" }, "targeting": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2 }, "maxItems": 50, "description": "ISO 3166-1 alpha-2 codes. At least one country or one location is required." }, "ageMin": { "type": "integer", "minimum": 13, "maximum": 65 }, "ageMax": { "type": "integer", "minimum": 13, "maximum": 65 }, "gender": { "type": "string", "enum": [ "all", "male", "female" ] }, "audienceIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 20 }, "locations": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "type": { "type": "string", "enum": [ "region", "city", "zip", "geo_market" ] } }, "required": [ "key", "name", "type" ] }, "maxItems": 200, "description": "Locations below country level, from `GET /v1/ads/targeting/search`" }, "interests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "id", "name" ] }, "maxItems": 100 }, "behaviors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "id", "name" ] }, "maxItems": 100 }, "income": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "id", "name" ] }, "maxItems": 10 }, "facets": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "id", "name" ] }, "maxItems": 100 }, "description": "Facets the network defines for itself, keyed by the type used with `GET /v1/ads/targeting/search` — `job_title`, `company_size`, `industry` and the rest of the B2B set on LinkedIn." } }, "required": [ "countries", "ageMin", "ageMax", "gender" ] } } }, "CreateNetworkAdRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "connectionId": { "type": "string", "format": "uuid", "description": "A Meta Ads connection in the workspace" }, "adSetId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Meta object id" }, "creativeId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "From `POST /v1/ads/creatives` or the creative library" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "paused": { "type": "boolean", "default": true, "description": "Create it paused; set to false to go live at once" } }, "required": [ "workspaceId", "connectionId", "adSetId", "creativeId", "name" ] }, "UpdateNetworkAdRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "creativeId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Meta object id" } } }, "DuplicateAdObjectRequest": { "type": "object", "properties": { "paused": { "type": "boolean", "default": true, "description": "Create it paused; set to false to go live at once" } } }, "BulkAdStatusRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "connectionId": { "type": "string", "format": "uuid", "description": "A Meta Ads connection in the workspace" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "objects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Meta object id" }, "level": { "type": "string", "enum": [ "campaign", "ad_set", "ad" ] } }, "required": [ "id", "level" ] }, "minItems": 1, "maxItems": 50 } }, "required": [ "workspaceId", "connectionId", "status", "objects" ] }, "CreateAdCreativeRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "connectionId": { "type": "string", "format": "uuid", "description": "A Meta Ads connection in the workspace" }, "adAccountId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Ad account id as the network addresses it: `act_…` on Meta, `urn:li:sponsoredAccount:…` on LinkedIn" }, "pageId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Facebook Page id on Meta, `urn:li:organization:…` on LinkedIn" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "format": { "type": "string", "enum": [ "image", "video", "carousel", "catalog", "partnership" ] }, "text": { "type": "string", "maxLength": 2000, "default": "", "description": "Primary text. Required except for `partnership`, which runs the creator's post" }, "headline": { "type": "string", "maxLength": 255 }, "destinationUrl": { "type": "string", "maxLength": 2048, "format": "uri" }, "callToAction": { "type": "string", "enum": [ "LEARN_MORE", "SHOP_NOW", "SIGN_UP", "SUBSCRIBE", "CONTACT_US", "DOWNLOAD", "GET_OFFER", "BOOK_NOW", "APPLY_NOW", "WATCH_MORE" ], "description": "Defaults to `LEARN_MORE`" }, "urlTags": { "type": "string", "maxLength": 1000, "pattern": "^[^\\s<>\"'`]*$", "description": "Query string appended to every link in the ad, e.g. `utm_source=meta&utm_medium=paid`" }, "mediaUrl": { "type": "string", "maxLength": 2048, "description": "A media library asset url: the image, or the video. Required for `video`" }, "thumbnailMediaUrl": { "type": "string", "maxLength": 2048, "description": "A video's poster frame, as a library image; Meta's own frame when omitted" }, "cards": { "type": "array", "items": { "type": "object", "properties": { "mediaUrl": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "A library image" }, "destinationUrl": { "type": "string", "maxLength": 2048, "format": "uri" }, "headline": { "type": "string", "maxLength": 255 }, "description": { "type": "string", "maxLength": 255 } }, "required": [ "mediaUrl" ] }, "minItems": 2, "maxItems": 10, "description": "Carousel cards; required for `carousel`" }, "productSetId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Required for `catalog`: Meta fills the cards from this product set" }, "description": { "type": "string", "maxLength": 255, "description": "`catalog` only: the per-product line under the headline" }, "creatorPostId": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[A-Za-z0-9_]+$", "description": "Required for `partnership`: the creator's Instagram media id, or their Page post as `{page}_{post}`" }, "creatorInstagramUserId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "`partnership` only: the creator's Instagram account" } }, "required": [ "workspaceId", "connectionId", "adAccountId", "pageId", "name", "format" ] }, "UpdateAudienceRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 500 } } }, "AddAudienceUsersRequest": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "minItems": 1, "maxItems": 10000, "description": "Hashed before they leave the API" } }, "required": [ "emails" ] }, "ReachEstimateRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "connectionId": { "type": "string", "format": "uuid", "description": "A Meta Ads connection in the workspace" }, "adAccountId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Ad account id as the network addresses it: `act_…` on Meta, `urn:li:sponsoredAccount:…` on LinkedIn" }, "pageId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Facebook Page id on Meta, `urn:li:organization:…` on LinkedIn" }, "targeting": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2 }, "maxItems": 50, "description": "ISO 3166-1 alpha-2 codes. At least one country or one location is required." }, "ageMin": { "type": "integer", "minimum": 13, "maximum": 65 }, "ageMax": { "type": "integer", "minimum": 13, "maximum": 65 }, "gender": { "type": "string", "enum": [ "all", "male", "female" ] }, "audienceIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 20 }, "locations": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "type": { "type": "string", "enum": [ "region", "city", "zip", "geo_market" ] } }, "required": [ "key", "name", "type" ] }, "maxItems": 200, "description": "Locations below country level, from `GET /v1/ads/targeting/search`" }, "interests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "id", "name" ] }, "maxItems": 100 }, "behaviors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "id", "name" ] }, "maxItems": 100 }, "income": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "id", "name" ] }, "maxItems": 10 }, "facets": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "id", "name" ] }, "maxItems": 100 }, "description": "Facets the network defines for itself, keyed by the type used with `GET /v1/ads/targeting/search` — `job_title`, `company_size`, `industry` and the rest of the B2B set on LinkedIn." } }, "required": [ "countries", "ageMin", "ageMax", "gender" ] } }, "required": [ "workspaceId", "connectionId", "adAccountId", "pageId", "targeting" ] }, "ArchiveLeadFormRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "connectionId": { "type": "string", "format": "uuid", "description": "A Meta Ads connection in the workspace" }, "pageId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Facebook Page id on Meta, `urn:li:organization:…` on LinkedIn" } }, "required": [ "workspaceId", "connectionId", "pageId" ] }, "SubscribeLeadPageRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "connectionId": { "type": "string", "format": "uuid", "description": "A Meta Ads connection in the workspace" }, "pageId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Facebook Page id on Meta, `urn:li:organization:…` on LinkedIn" } }, "required": [ "workspaceId", "connectionId", "pageId" ] }, "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable snake_case error code" }, "message": { "type": "string", "description": "Human-readable explanation; may change" } }, "required": [ "error", "message" ], "additionalProperties": true, "description": "The one error envelope, on every endpoint including an unknown route (`not_found`) and a server fault (`internal_error`). Some errors carry additional context fields (for example `retry_after`, `upgrade_url`, `issues`). Every response also carries an `X-Request-Id` header to quote to support." }, "PageMeta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer", "description": "At least 1, so an empty list is one empty page" } }, "required": [ "page", "per_page", "total", "total_pages" ] }, "CursorMeta": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Pass back as `cursor` for the next page; null on the last page" }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ] }, "MediaItem": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video", "gif" ] }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "size": { "type": "number", "description": "File size in bytes" }, "alt": { "type": "string" }, "thumbnail": { "type": "string", "format": "uri" }, "media_id": { "type": "string", "format": "uuid", "description": "Library id, when the file is stored in the workspace media library" }, "preview_url": { "type": "string", "format": "uri", "description": "A link that renders the stored file; present for files held in FoPost storage" } }, "required": [ "type", "name", "url" ] }, "PostContentBlock": { "type": "object", "properties": { "id": { "type": "integer" }, "text": { "type": [ "string", "null" ] }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/MediaItem" } }, "position": { "type": "integer" } } }, "PostAccountResult": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Social account id" }, "platform": { "type": "string" }, "username": { "type": "string" }, "name": { "type": "string" }, "avatar": { "type": [ "string", "null" ] }, "publish_status": { "type": "string", "enum": [ "pending", "queued", "delayed", "publishing", "published", "failed", "cancelled", "unpublished" ] }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "platform_post_id": { "type": [ "string", "null" ] }, "external_url": { "type": [ "string", "null" ] }, "remote_delete": { "type": "boolean", "description": "True when unpublishing, or deleting with `remove_from_platform`, can take this published post down on the network" }, "remote_edit": { "type": "boolean", "description": "True when updating the post also changes this published post in place on the network" }, "error_code": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ], "description": "User-friendly error message" }, "raw_error_message": { "type": [ "string", "null" ], "description": "Raw error message from the platform" }, "attempts": { "type": "integer" }, "max_attempts": { "type": "integer" }, "scheduled_publish_at": { "type": [ "string", "null" ], "format": "date-time" }, "delay_reason": { "type": [ "string", "null" ] }, "delay_message": { "type": [ "string", "null" ] } } }, "RemoteEdit": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid", "description": "Social account id" }, "platform": { "type": "string" }, "edited": { "type": "boolean", "description": "False when the network refused the change" }, "error": { "type": [ "string", "null" ] } }, "required": [ "account_id", "platform", "edited", "error" ] }, "UnpublishResponse": { "type": "object", "properties": { "post_status": { "type": "string", "enum": [ "draft", "scheduled", "publishing", "published", "partially_failed", "failed", "cancelled", "unpublished" ] }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/PlatformRemoval" }, "description": "One entry per network the post was live on" } }, "required": [ "post_status", "deliveries" ] }, "PlatformRemoval": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid", "description": "Social account id" }, "platform": { "type": "string" }, "removed": { "type": "boolean", "description": "False when the network refused to take the post down" } }, "required": [ "account_id", "platform", "removed" ] }, "PostDeleteResponse": { "type": "object", "properties": { "platform_removals": { "type": "array", "items": { "$ref": "#/components/schemas/PlatformRemoval" }, "description": "One entry per network asked to remove the post; empty unless `remove_from_platform` was set" } }, "required": [ "platform_removals" ] }, "PostLabelRef": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string" } } }, "Post": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "publishing", "published", "partially_failed", "failed", "cancelled", "unpublished" ] }, "content_type": { "type": "string", "enum": [ "post", "thread", "reel" ] }, "artifact_type": { "type": "string", "description": "What the post is, e.g. `text_post`" }, "schedule_at": { "type": [ "string", "null" ], "format": "date-time" }, "schedule_mode": { "type": "string", "enum": [ "manual", "queue" ], "description": "`queue` when the time was assigned from a posting slot" }, "repeatable": { "type": "boolean" }, "repeatable_times": { "type": [ "integer", "null" ] }, "repeatable_gap": { "type": [ "integer", "null" ] }, "repeatable_gap_unit": { "type": [ "string", "null" ], "enum": [ "hours", "days", "weeks", "months", null ] }, "remaining_posts": { "type": [ "integer", "null" ] }, "title": { "type": [ "string", "null" ] }, "internal_title": { "type": [ "string", "null" ], "description": "Internal name, never published" }, "summary": { "type": [ "string", "null" ] }, "origin": { "type": "string", "enum": [ "user", "agent", "automation" ], "description": "Who created the post" }, "auto_plug": { "type": "boolean" }, "auto_plug_content": { "type": [ "string", "null" ] }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "rejection_reason": { "type": [ "string", "null" ] }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/PostContentBlock" } }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/PostAccountResult" } }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/PostLabelRef" } }, "campaign": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "null" } ] }, "companion_of": { "type": [ "string", "null" ], "format": "uuid", "description": "Id of the post this one accompanies" }, "settings": { "type": "object", "description": "Per-account platform settings, keyed by account id", "additionalProperties": { "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "remote_edits": { "type": "array", "items": { "$ref": "#/components/schemas/RemoteEdit" }, "description": "Present only on an update to a published post: what each network answered" } }, "required": [ "id", "workspace_id", "status", "content_type", "content", "accounts", "labels" ] }, "PostListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "QueueSlot": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "account_id": { "type": [ "string", "null" ], "format": "uuid", "description": "null when the slot applies to every account" }, "weekday": { "type": "integer", "minimum": 0, "maximum": 6, "description": "0 = Sunday … 6 = Saturday" }, "time": { "type": "string", "description": "HH:MM, 24-hour, in `timezone`" }, "timezone": { "type": "string", "description": "IANA zone name" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspace_id", "account_id", "weekday", "time", "timezone", "created_at" ] }, "QueueMove": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Post id" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "required": [ "id", "from", "to" ] }, "QueueSlotUpdated": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "account_id": { "type": [ "string", "null" ], "format": "uuid" }, "weekday": { "type": "integer" }, "time": { "type": "string" }, "timezone": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "moved": { "type": "array", "items": { "$ref": "#/components/schemas/QueueMove" }, "description": "Queued posts moved to a new slot because of this change" } }, "required": [ "id", "workspace_id", "account_id", "weekday", "time", "timezone", "moved" ] }, "QueueSlotDeleted": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "moved": { "type": "array", "items": { "$ref": "#/components/schemas/QueueMove" } } }, "required": [ "deleted", "moved" ] }, "QueueNext": { "type": "object", "properties": { "next": { "type": [ "string", "null" ], "format": "date-time", "description": "null when no slot applies" } }, "required": [ "next" ] }, "HealthWarning": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "health_status": { "type": "string" }, "message": { "type": "string" } } }, "PublishDelivery": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Delivery id" }, "account_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "queued", "delayed", "publishing", "published", "failed", "cancelled", "unpublished" ] }, "error_code": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "platform_post_id": { "type": [ "string", "null" ] }, "external_url": { "type": [ "string", "null" ] }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "attempts": { "type": "integer" }, "scheduled_publish_at": { "type": [ "string", "null" ], "format": "date-time" }, "delay_reason": { "type": [ "string", "null" ] }, "delay_message": { "type": [ "string", "null" ] } } }, "PublishResponse": { "type": "object", "properties": { "post_status": { "type": "string", "enum": [ "draft", "scheduled", "publishing", "published", "partially_failed", "failed", "cancelled", "unpublished" ] }, "held": { "type": "boolean", "const": true, "description": "Present when the workspace requires approval: the post is held as `pending_approval` and nothing was queued" }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/PublishDelivery" }, "description": "Absent when `held`" }, "health_warnings": { "type": "array", "items": { "$ref": "#/components/schemas/HealthWarning" }, "description": "Absent when `held`" } }, "required": [ "post_status" ] }, "DryRunResponse": { "type": "object", "properties": { "dry_run": { "type": "boolean", "const": true }, "post": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "publishing", "published", "partially_failed", "failed", "cancelled", "unpublished" ] } } }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" } } } }, "health_warnings": { "type": "array", "items": { "$ref": "#/components/schemas/HealthWarning" } } }, "required": [ "dry_run", "post", "accounts", "health_warnings" ] }, "RetryResponse": { "type": "object", "properties": { "post_status": { "type": "string", "enum": [ "draft", "scheduled", "publishing", "published", "partially_failed", "failed", "cancelled", "unpublished" ] }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/PublishDelivery" } }, "exceeded": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "attempts": { "type": "integer" } } }, "description": "Deliveries skipped because they exceeded the retry limit" } }, "required": [ "post_status", "deliveries", "exceeded" ] }, "CancelResponse": { "type": "object", "properties": { "post_status": { "type": "string", "enum": [ "draft", "scheduled", "publishing", "published", "partially_failed", "failed", "cancelled", "unpublished" ] }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "account_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "queued", "delayed", "publishing", "published", "failed", "cancelled", "unpublished" ] } } } } }, "required": [ "post_status", "deliveries" ] }, "ContentSignal": { "type": "object", "properties": { "level": { "type": "string", "enum": [ "info", "warn" ] }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "level", "code", "message" ] }, "PreflightResponse": { "type": "object", "properties": { "ready": { "type": "boolean" }, "post": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "publishing", "published", "partially_failed", "failed", "cancelled", "unpublished" ] } } }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" }, "delivery": { "type": "string", "enum": [ "api", "extension" ], "description": "`extension` for a network posted through the browser extension" }, "ready": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "string" }, "description": "Hard blockers that prevent publishing" }, "score": { "type": "number", "description": "Advisory 0-100 content quality score for this platform" }, "signals": { "type": "array", "items": { "$ref": "#/components/schemas/ContentSignal" }, "description": "Advisory signals — they never block publishing" } } } } }, "required": [ "ready", "post", "accounts" ] }, "ValidatePostResponse": { "type": "object", "properties": { "ready": { "type": "boolean" }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "ready": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "string" }, "description": "Hard blockers that would prevent publishing" }, "score": { "type": "number", "description": "Advisory 0-100 content quality score for this platform" }, "signals": { "type": "array", "items": { "$ref": "#/components/schemas/ContentSignal" }, "description": "Advisory signals — they never block publishing" } } } } }, "required": [ "ready", "platforms" ] }, "ValidateLengthResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "length": { "type": "integer", "description": "What the platform counts, in `unit`" }, "limit": { "type": [ "integer", "null" ], "description": "The platform limit; null when it has none" }, "unit": { "type": "string", "enum": [ "chars", "bytes" ] }, "ok": { "type": "boolean" }, "signals": { "type": "array", "items": { "$ref": "#/components/schemas/ContentSignal" } } } } } }, "required": [ "ok", "platforms" ] }, "ValidateMediaResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string" }, "size": { "type": "integer", "description": "Bytes fetched" }, "mime_type": { "type": "string", "description": "The verified type; absent when the file failed" }, "type": { "type": "string", "description": "image, video, audio or document; absent when the file failed" } }, "required": [ "ok", "issues", "name", "size" ] }, "Delivery": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "account_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "queued", "delayed", "publishing", "published", "failed", "cancelled", "unpublished" ] }, "error_code": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "attempts": { "type": "integer" }, "max_attempts": { "type": "integer" }, "scheduled_publish_at": { "type": [ "string", "null" ], "format": "date-time" }, "delay_reason": { "type": [ "string", "null" ] }, "delay_message": { "type": [ "string", "null" ] }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "platform_post_id": { "type": [ "string", "null" ] }, "external_url": { "type": [ "string", "null" ] }, "platform": { "type": "string" }, "username": { "type": "string" }, "account_name": { "type": "string" } } }, "PublishRunDelivery": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid" }, "account_name": { "type": "string" }, "username": { "type": "string" }, "platform": { "type": "string" }, "status": { "type": "string" }, "attempt_number": { "type": "integer" }, "error_code": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "platform_post_id": { "type": [ "string", "null" ] }, "external_url": { "type": [ "string", "null" ] }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "duration_ms": { "type": [ "integer", "null" ] } } }, "PublishRun": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "run_number": { "type": "integer" }, "status": { "type": "string", "enum": [ "running", "published", "partially_failed", "failed", "cancelled" ] }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/PublishRunDelivery" } } } }, "BulkImportRowResult": { "type": "object", "properties": { "row": { "type": "integer" }, "content_preview": { "type": "string" }, "content_type": { "type": "string", "enum": [ "post", "thread" ] }, "thread_parts": { "type": [ "integer", "null" ], "description": "Number of thread parts; null unless a thread" }, "schedule_at": { "type": [ "string", "null" ], "format": "date-time" }, "repeat": { "oneOf": [ { "type": "object", "properties": { "times": { "type": "integer" }, "gap": { "type": "integer" }, "unit": { "type": "string" } }, "required": [ "times", "gap", "unit" ] }, { "type": "null" } ] }, "accounts": { "type": "array", "items": { "type": "string" } }, "labels": { "type": "integer" }, "has_media": { "type": "boolean" }, "media_count": { "type": "integer" }, "captions": { "type": "integer", "description": "Accounts with a per-platform caption override" }, "errors": { "type": "array", "items": { "type": "string" } } } }, "BulkImportValidation": { "type": "object", "properties": { "total_rows": { "type": "integer" }, "valid_rows": { "type": "integer" }, "invalid_rows": { "type": "integer" }, "max_rows": { "type": "integer", "description": "The most data rows one import accepts" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/BulkImportRowResult" } } }, "required": [ "total_rows", "valid_rows", "invalid_rows", "max_rows", "rows" ] }, "BulkImportCommitResult": { "type": "object", "properties": { "batch_id": { "type": "string", "format": "uuid" }, "created": { "type": "integer" }, "held_for_approval": { "type": "boolean", "description": "True when the workspace requires approval and the posts are held" }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "schedule_at": { "type": [ "string", "null" ], "format": "date-time" } } } } }, "required": [ "batch_id", "created", "held_for_approval", "posts" ] }, "PostAnalyticsMetrics": { "type": "object", "properties": { "impressions": { "type": [ "integer", "null" ] }, "reach": { "type": [ "integer", "null" ] }, "engagements": { "type": [ "integer", "null" ] }, "likes": { "type": [ "integer", "null" ] }, "comments": { "type": [ "integer", "null" ] }, "shares": { "type": [ "integer", "null" ] }, "reposts": { "type": [ "integer", "null" ] }, "clicks": { "type": [ "integer", "null" ] }, "saves": { "type": [ "integer", "null" ] }, "video_views": { "type": [ "integer", "null" ] }, "watch_time_ms": { "type": [ "integer", "null" ] }, "avg_watch_time_ms": { "type": [ "integer", "null" ] }, "reactions_breakdown": { "type": [ "object", "null" ], "additionalProperties": { "type": "integer" } }, "follows": { "type": [ "integer", "null" ] }, "fetched_at": { "type": "string", "format": "date-time" } } }, "PostAnalyticsResponse": { "type": "object", "properties": { "post_id": { "type": "string", "format": "uuid" }, "totals": { "type": "object", "properties": { "impressions": { "type": "integer" }, "reach": { "type": "integer" }, "engagements": { "type": "integer" }, "likes": { "type": "integer" }, "comments": { "type": "integer" }, "shares": { "type": "integer" }, "reposts": { "type": "integer" }, "clicks": { "type": "integer" }, "saves": { "type": "integer" }, "video_views": { "type": "integer" }, "follows": { "type": "integer" } } }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "username": { "type": "string" }, "external_post_id": { "type": [ "string", "null" ] }, "permalink": { "type": [ "string", "null" ] }, "thumbnail_url": { "type": [ "string", "null" ] }, "media_type": { "type": [ "string", "null" ] }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "metrics": { "oneOf": [ { "$ref": "#/components/schemas/PostAnalyticsMetrics" }, { "type": "null" } ] } } } }, "last_fetched_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "post_id", "totals", "platforms", "last_fetched_at" ] }, "WorkspaceAccountRef": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid", "description": "Present on the list response" }, "platform": { "type": "string" }, "username": { "type": "string" }, "name": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "platform", "username", "name", "avatar" ] }, "Workspace": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "type": { "type": "string" }, "logo": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "timezone": { "type": "string" }, "country": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "language": { "type": "string" }, "require_approval": { "type": "boolean" }, "ai_alt_text_enabled": { "type": "boolean" }, "brand_color": { "type": [ "string", "null" ], "description": "Hex accent colour for client-facing surfaces" }, "connect_redirect_domains": { "type": "array", "items": { "type": "string" }, "description": "Hostnames a hosted connect session may redirect the end user to" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "description": "Absent on the list response" } }, "required": [ "id", "name", "slug", "type", "timezone", "language", "require_approval", "ai_alt_text_enabled", "connect_redirect_domains", "created_at" ] }, "WorkspaceWithAccounts": { "allOf": [ { "$ref": "#/components/schemas/Workspace" }, { "type": "object", "properties": { "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceAccountRef" } } }, "required": [ "accounts" ] } ] }, "WorkspaceListItem": { "allOf": [ { "$ref": "#/components/schemas/Workspace" }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "owner", "admin", "member" ], "description": "The caller's role" }, "bypass_abilities": { "type": "array", "items": { "type": "string", "enum": [ "accounts", "api", "ai" ] }, "description": "Billing bypasses granted to the workspace payer" }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceAccountRef" } } }, "required": [ "role", "bypass_abilities", "accounts" ] } ] }, "WorkspaceAnalyticsResponse": { "type": "object", "properties": { "workspace_id": { "type": "string", "format": "uuid" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" }, "followers": { "type": [ "integer", "null" ] }, "following": { "type": [ "integer", "null" ] }, "total_posts": { "type": [ "integer", "null" ] }, "fetched_at": { "type": [ "string", "null" ], "format": "date-time" } } } }, "totals": { "type": "object", "properties": { "followers": { "type": "integer" }, "total_posts": { "type": "integer" } } } }, "required": [ "workspace_id", "accounts", "totals" ] }, "AccountSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" }, "name": { "type": "string", "description": "The display name override when set, else the platform name" }, "platform_name": { "type": "string" }, "avatar": { "type": [ "string", "null" ] }, "is_primary": { "type": "boolean" }, "active": { "type": "boolean" }, "health_status": { "type": [ "string", "null" ], "enum": [ "healthy", "degraded", "expired", "revoked", "unknown", null ] }, "last_health_check": { "type": [ "string", "null" ], "format": "date-time" }, "external_user_id": { "type": [ "string", "null" ], "description": "Your own id for the end user who connected through a hosted connect link" } } }, "ConnectSession": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "used", "expired" ] }, "external_user_id": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "twitter", "instagram", "linkedin", "threads", "tiktok", "youtube", "reddit", "tumblr", "dribbble" ] } }, "redirect_url": { "type": [ "string", "null" ] }, "branding": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] } } }, "account_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The connected account, once the session is used" }, "url": { "type": "string", "description": "The hosted link to hand to your user. Present on creation only." }, "expires_at": { "type": "string", "format": "date-time" }, "used_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "status", "external_user_id", "platforms", "expires_at", "created_at" ] }, "TelegramConnectCode": { "type": "object", "properties": { "code": { "type": "string", "description": "One-time code, valid for 15 minutes" }, "command": { "type": "string", "description": "What to send in the chat: `/connect `" }, "bot_username": { "type": [ "string", "null" ], "description": "The publishing bot, without the @" }, "deep_link": { "type": [ "string", "null" ], "description": "Opens a private chat with the bot, code included" }, "group_link": { "type": [ "string", "null" ], "description": "Adds the bot to a group, code included" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "code", "command", "expires_at" ] }, "TelegramConnectStatus": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "connected", "failed", "expired" ] }, "account_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The connected account, once `connected`" }, "reason": { "type": [ "string", "null" ], "enum": [ "card_required", "slot_taken", "workspace_unavailable", null ], "description": "Why the connection failed, when `failed`" } }, "required": [ "status", "account_id", "reason" ] }, "TelegramBotCommands": { "type": "object", "properties": { "commands": { "type": "array", "items": { "type": "object", "properties": { "command": { "type": "string" }, "description": { "type": "string" } }, "required": [ "command", "description" ] } } }, "required": [ "commands" ] }, "MetaIceBreakers": { "type": "object", "properties": { "ice_breakers": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string" }, "payload": { "type": "string" } }, "required": [ "question", "payload" ] } } }, "required": [ "ice_breakers" ] }, "MetaPersistentMenu": { "type": "object", "properties": { "persistent_menu": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string" }, "composer_input_disabled": { "type": "boolean" }, "call_to_actions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "postback", "web_url" ] }, "title": { "type": "string" }, "payload": { "type": "string" }, "url": { "type": "string" } }, "required": [ "type", "title" ] } } }, "required": [ "locale", "call_to_actions" ] } } }, "required": [ "persistent_menu" ] }, "MetaGreeting": { "type": "object", "properties": { "greeting": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string" }, "text": { "type": "string" } }, "required": [ "locale", "text" ] } } }, "required": [ "greeting" ] }, "WebhookSubscription": { "type": "object", "properties": { "subscribed": { "type": "boolean", "description": "True when the app is subscribed and every required field is present" }, "fields": { "type": "array", "items": { "type": "string" }, "description": "The fields the network reports as subscribed" }, "missing_fields": { "type": "array", "items": { "type": "string" }, "description": "Required fields the network is not delivering" } }, "required": [ "subscribed", "fields", "missing_fields" ] }, "AccountCreated": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" }, "name": { "type": "string" }, "avatar": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AccountDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": [ "string", "null" ], "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" }, "name": { "type": "string", "description": "The display name override when set, else the platform name" }, "platform_name": { "type": "string" }, "avatar": { "type": [ "string", "null" ] }, "workspace": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "type": { "type": "string" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AccountGroup": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "account_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AccountHealth": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" }, "active": { "type": "boolean" }, "health_status": { "type": [ "string", "null" ], "enum": [ "healthy", "degraded", "expired", "revoked", "unknown", null ] }, "last_health_check": { "type": [ "string", "null" ], "format": "date-time" }, "token_expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "permissions": { "type": [ "array", "null" ], "items": { "type": "string" } }, "capabilities": { "type": [ "object", "null" ], "properties": { "publish": { "type": "boolean" }, "analytics": { "type": "boolean" }, "inbox": { "type": "boolean" }, "inbox_reply": { "type": "boolean" }, "messages": { "type": "boolean" }, "remote_delete": { "type": "boolean" }, "radar": { "type": "boolean" } } } } }, "AccountsHealthSummaryResponse": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" }, "health_status": { "type": "string", "enum": [ "healthy", "degraded", "expired", "revoked", "unknown" ] }, "last_health_check": { "type": [ "string", "null" ], "format": "date-time" } } } }, "summary": { "type": "object", "properties": { "total": { "type": "integer" }, "healthy": { "type": "integer" }, "degraded": { "type": "integer" }, "expired": { "type": "integer" }, "revoked": { "type": "integer" }, "unknown": { "type": "integer" } } } }, "required": [ "accounts", "summary" ] }, "Community": { "type": "object", "properties": { "id": { "type": "integer", "description": "Internal id (use for delete)" }, "account_id": { "type": "string", "format": "uuid" }, "community_id": { "type": "string", "description": "X community id" }, "name": { "type": "string" }, "member_count": { "type": [ "integer", "null" ] }, "description": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "last_synced_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "description": "X (Twitter) community linked to a connected account" }, "LabelWorkspaceRef": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "type": { "type": "string" }, "logo": { "type": [ "string", "null" ] }, "timezone": { "type": "string" }, "language": { "type": "string" } } }, "Label": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string", "description": "Hex color, e.g. #ff0000" }, "workspace": { "oneOf": [ { "$ref": "#/components/schemas/LabelWorkspaceRef" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "color", "workspace" ] }, "LabelListItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string" }, "workspace": { "oneOf": [ { "$ref": "#/components/schemas/LabelWorkspaceRef" }, { "type": "null" } ] } }, "required": [ "id", "name", "color", "workspace" ] }, "RequestLog": { "type": "object", "properties": { "id": { "type": "integer" }, "workspace_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Workspace the request ran against; null for account-level requests" }, "time": { "type": "string", "format": "date-time" }, "auth_method": { "type": "string", "enum": [ "jwt", "api_key" ] }, "method": { "type": "string" }, "route": { "type": "string", "description": "Route pattern, e.g. /v1/posts/{id}" }, "path": { "type": "string" }, "status_code": { "type": "integer" }, "duration_ms": { "type": "integer" }, "platform": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ], "description": "Error text for failed requests" } } }, "RequestLogBucket": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time" }, "total": { "type": "integer" }, "errors": { "type": "integer" } } }, "RequestLogListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RequestLog" } }, "meta": { "$ref": "#/components/schemas/CursorMeta", "description": "Pass `next_cursor` back as `before` for the next page" }, "summary": { "type": "object", "properties": { "since": { "type": "string", "format": "date-time" }, "total": { "type": "integer" }, "errors": { "type": "integer" }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/RequestLogBucket" } } } } }, "required": [ "data", "meta", "summary" ] }, "ActivityEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "publish", "connection", "webhook", "inbox", "automation", "billing", "security" ] }, "ref_type": { "type": [ "string", "null" ], "description": "What the event is about, e.g. post" }, "ref_id": { "type": [ "string", "null" ] }, "summary": { "type": "string" }, "actor": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user", "api_key", "agent", "system" ] }, "name": { "type": [ "string", "null" ] } } }, "time": { "type": "string", "format": "date-time" } } }, "ActivityListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityEvent" } }, "meta": { "$ref": "#/components/schemas/CursorMeta" } }, "required": [ "data", "meta" ] }, "WebhookEvent": { "type": "string", "enum": [ "post.scheduled", "post.published", "post.partially_failed", "post.failed", "post.deleted", "delivery.published", "delivery.failed", "delivery.delayed", "account.connected", "account.disconnected", "account.health_changed", "article.published", "inbox.comment_received", "inbox.mention_received", "inbox.message_received", "inbox.review_received", "automation.triggered", "automation.completed", "automation.failed" ] }, "WebhookHeaderNames": { "type": "array", "items": { "type": "string" }, "description": "Names of the custom headers sent with every delivery. Values are write-only." }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": [ "string", "null" ], "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "header_names": { "$ref": "#/components/schemas/WebhookHeaderNames" }, "active": { "type": "boolean" }, "last_triggered_at": { "type": [ "string", "null" ], "format": "date-time" }, "failure_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "webhook_id": { "type": "string", "format": "uuid" }, "event": { "$ref": "#/components/schemas/WebhookEvent" }, "delivery_key": { "type": "string", "description": "The X-FoPost-Delivery id; every attempt of one event shares it" }, "attempt": { "type": "integer", "description": "1 for the first send; retries and redeliveries count up" }, "status": { "type": "string", "enum": [ "success", "failed" ] }, "response_status": { "type": [ "integer", "null" ], "description": "Null when no response arrived" }, "response_snippet": { "type": [ "string", "null" ], "description": "Up to 500 characters of what the endpoint answered, secrets redacted" }, "duration_ms": { "type": "integer" }, "payload_hash": { "type": "string", "description": "SHA-256 of the body that was sent" }, "next_retry_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "WebhookDeliveryDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "webhook_id": { "type": "string", "format": "uuid" }, "event": { "$ref": "#/components/schemas/WebhookEvent" }, "delivery_key": { "type": "string" }, "attempt": { "type": "integer" }, "status": { "type": "string", "enum": [ "success", "failed" ] }, "response_status": { "type": [ "integer", "null" ] }, "response_snippet": { "type": [ "string", "null" ] }, "duration_ms": { "type": "integer" }, "payload_hash": { "type": "string" }, "next_retry_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "payload": { "type": "object", "description": "The body exactly as it was sent" } } }, "WebhookCreated": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" }, "secret": { "type": "string", "description": "Signing secret for verifying webhook payloads. Returned only once, on creation." }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "header_names": { "$ref": "#/components/schemas/WebhookHeaderNames" }, "active": { "type": "boolean" }, "last_triggered_at": { "type": [ "string", "null" ], "format": "date-time" }, "failure_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspace_id", "url", "secret", "events", "header_names", "active" ] }, "WebhookUpdated": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": [ "string", "null" ], "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "header_names": { "$ref": "#/components/schemas/WebhookHeaderNames" }, "active": { "type": "boolean" }, "last_triggered_at": { "type": [ "string", "null" ], "format": "date-time" }, "failure_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "secret": { "type": "string", "description": "Present only when this request rotated the secret. Returned once." } } }, "AnalyticsOverviewResponse": { "type": "object", "properties": { "total_accounts": { "type": "integer" }, "total_followers": { "type": "integer" }, "total_posts": { "type": "integer", "description": "Posts observed in the selected period" }, "total_engagement": { "type": "integer" }, "total_impressions": { "type": "integer" }, "total_reach": { "type": "integer" }, "total_likes": { "type": "integer" }, "total_comments": { "type": "integer" }, "total_shares": { "type": "integer" }, "total_reposts": { "type": "integer" }, "total_saves": { "type": "integer" }, "total_clicks": { "type": "integer" }, "total_video_views": { "type": "integer" }, "total_profile_views": { "type": "integer" }, "engagement_rate": { "type": [ "number", "null" ], "description": "Engagement / reach (or impressions); null without data" }, "deltas": { "type": "object", "properties": { "followers": { "type": [ "number", "null" ] }, "posts": { "type": [ "number", "null" ] }, "engagement": { "type": [ "number", "null" ] }, "impressions": { "type": [ "number", "null" ] }, "likes": { "type": [ "number", "null" ] }, "comments": { "type": [ "number", "null" ] }, "shares": { "type": [ "number", "null" ] }, "profile_views": { "type": [ "number", "null" ] } }, "description": "Percentage change vs the previous period. Post-level metric deltas are always null (platforms only expose lifetime counts per post)." }, "today_stats": { "type": "object", "properties": { "posts": { "type": "integer" }, "follower_change": { "type": "integer" }, "engagement": { "type": "integer" } } }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "accounts": { "type": "integer" }, "followers": { "type": "integer" } } } }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" }, "name": { "type": "string" }, "avatar": { "type": [ "string", "null" ] }, "followers": { "type": [ "integer", "null" ] }, "total_posts": { "type": [ "integer", "null" ] }, "fetched_at": { "type": [ "string", "null" ], "format": "date-time" }, "history": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "followers": { "type": [ "integer", "null" ] } } }, "description": "Daily follower history (up to 30 days, oldest first)" } } } } } }, "TimeSeriesResponse": { "type": "object", "properties": { "days": { "type": "integer" }, "series": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "engagements": { "type": "integer" }, "impressions": { "type": "integer" }, "likes": { "type": "integer" }, "comments": { "type": "integer" }, "shares": { "type": "integer" }, "followers": { "type": "integer" }, "posts": { "type": "integer" } } } } }, "required": [ "days", "series" ] }, "TopPost": { "type": "object", "properties": { "rank": { "type": "integer" }, "post_id": { "type": [ "string", "null" ], "format": "uuid", "description": "FoPost post id, or null for platform-native posts" }, "external_post_id": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "fopost", "platform" ] }, "preview": { "type": [ "string", "null" ], "description": "First 200 characters of the post text" }, "permalink": { "type": [ "string", "null" ] }, "thumbnail_url": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "username": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "removed": { "type": "boolean", "description": "The post was deleted on the network" } } } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string" } } }, "description": "Labels on the post — always empty for platform-native posts" }, "metrics": { "type": "object", "properties": { "engagements": { "type": "integer" }, "impressions": { "type": "integer" }, "reach": { "type": "integer" }, "likes": { "type": "integer" }, "comments": { "type": "integer" }, "shares": { "type": "integer" }, "reposts": { "type": "integer" }, "clicks": { "type": "integer" }, "saves": { "type": "integer" }, "video_views": { "type": "integer" } } } } }, "LabelAnalytics": { "type": "object", "properties": { "label_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string" }, "post_count": { "type": "integer" }, "impressions": { "type": "integer" }, "reach": { "type": "integer" }, "engagements": { "type": "integer" }, "likes": { "type": "integer" }, "comments": { "type": "integer" }, "shares": { "type": "integer" }, "engagement_rate": { "type": [ "number", "null" ], "description": "Engagements over reach, falling back to impressions; null when neither exists" }, "follower_delta": { "type": [ "integer", "null" ], "description": "Follows gained across the campaign, or null when no platform reports it" } } }, "PostsTableResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "post_id": { "type": "string", "format": "uuid" }, "preview": { "type": [ "string", "null" ], "description": "First 120 characters of the post text" }, "status": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time" }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "username": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "delivery_status": { "type": "string", "enum": [ "pending", "queued", "delayed", "publishing", "published", "failed", "cancelled", "unpublished" ] } } } }, "delivery_summary": { "type": "object", "properties": { "total": { "type": "integer" }, "published": { "type": "integer" }, "failed": { "type": "integer" }, "pending": { "type": "integer" } } } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" }, "summary": { "type": "object", "properties": { "draft": { "type": "integer" }, "scheduled": { "type": "integer" }, "published": { "type": "integer" }, "failed": { "type": "integer" }, "pending": { "type": "integer" }, "total": { "type": "integer" } }, "description": "Post counts by status across the whole filtered set" } }, "required": [ "data", "meta", "summary" ] }, "InboxAnalyticsResponse": { "type": "object", "properties": { "totals": { "type": "object", "properties": { "received": { "type": "integer" }, "sent": { "type": "integer" }, "answered": { "type": "integer", "description": "Inbound items that got a reply" }, "open": { "type": "integer", "description": "Inbound items still unread or read, not resolved" }, "conversations": { "type": "integer" }, "median_response_minutes": { "type": [ "number", "null" ], "description": "Median minutes from an inbound item to its first reply; null without replies" } } }, "deltas": { "type": "object", "properties": { "received": { "type": [ "number", "null" ] }, "sent": { "type": [ "number", "null" ] }, "answered": { "type": [ "number", "null" ] } }, "description": "Percentage change vs the previous period of the same length" }, "series": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "received": { "type": "integer" }, "sent": { "type": "integer" }, "answered": { "type": "integer" } } } }, "by_platform": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "received": { "type": "integer" }, "sent": { "type": "integer" } } } }, "by_type": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "comment", "mention", "reply", "dm", "review" ] }, "count": { "type": "integer" } } } }, "by_account": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" }, "name": { "type": "string" }, "avatar": { "type": [ "string", "null" ] }, "received": { "type": "integer" }, "sent": { "type": "integer" } } } }, "response_time": { "type": "array", "items": { "type": "object", "properties": { "bucket": { "type": "string", "enum": [ "under_1h", "1h_6h", "6h_24h", "1d_3d", "over_3d" ] }, "count": { "type": "integer" } } } }, "heatmap": { "type": "array", "items": { "type": "object", "properties": { "weekday": { "type": "integer", "minimum": 0, "maximum": 6, "description": "0 = Sunday" }, "hour": { "type": "integer", "minimum": 0, "maximum": 23 }, "count": { "type": "integer" } } } }, "time_zone": { "type": "string" } } }, "PostingStreakResponse": { "type": "object", "properties": { "streak": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "count": { "type": "integer" }, "published_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "scheduled_count": { "type": "integer" } } } } }, "required": [ "streak" ] }, "DemographicsBucket": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "number" }, "share": { "type": "number", "description": "Fraction of the dimension total (0-1)" } }, "required": [ "key", "value", "share" ] }, "DemographicsResponse": { "type": "object", "properties": { "audience": { "type": "string", "enum": [ "followers", "engaged", "reached" ] }, "dimensions": { "type": "object", "properties": { "age": { "type": "array", "items": { "$ref": "#/components/schemas/DemographicsBucket" } }, "gender": { "type": "array", "items": { "$ref": "#/components/schemas/DemographicsBucket" } }, "country": { "type": "array", "items": { "$ref": "#/components/schemas/DemographicsBucket" } }, "city": { "type": "array", "items": { "$ref": "#/components/schemas/DemographicsBucket" } } } }, "contributing_accounts": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" } } } }, "unsupported_accounts": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" } } } } }, "required": [ "audience", "dimensions", "contributing_accounts", "unsupported_accounts" ] }, "ContentDecayResponse": { "type": "object", "properties": { "days": { "type": "integer" }, "posts_measured": { "type": "integer", "description": "Posts with a publish time and a later reading" }, "half_life_bucket": { "type": [ "string", "null" ], "description": "First age band where the average post had reached half its final engagement" }, "bands": { "type": "array", "items": { "type": "object", "properties": { "bucket": { "type": "string", "enum": [ "under_1h", "1h_3h", "3h_6h", "6h_12h", "12h_24h", "1d_3d", "3d_7d", "over_7d" ] }, "label": { "type": "string" }, "posts": { "type": "integer", "description": "Posts with at least one reading in this band" }, "avg_engagements": { "type": "number" }, "avg_impressions": { "type": "number" }, "share_of_final": { "type": [ "number", "null" ], "description": "Mean share of the post's final engagement reached here (0-1)" } } } } }, "required": [ "days", "posts_measured", "half_life_bucket", "bands" ] }, "PostingFrequencyResponse": { "type": "object", "properties": { "days": { "type": "integer" }, "weeks": { "type": "array", "items": { "type": "object", "properties": { "week_start": { "type": "string", "format": "date", "description": "Monday of the week, UTC" }, "posts": { "type": "integer" }, "engagements": { "type": "integer" }, "avg_engagements_per_post": { "type": "number" } } } }, "bands": { "type": "array", "items": { "type": "object", "properties": { "band": { "type": "string", "enum": [ "under_3", "3_5", "6_10", "over_10" ] }, "label": { "type": "string" }, "weeks": { "type": "integer" }, "posts": { "type": "integer" }, "avg_posts_per_week": { "type": "number" }, "avg_engagements_per_post": { "type": "number" }, "engagement_rate": { "type": [ "number", "null" ], "description": "Engagements over reach, impressions as the stand-in" } } } }, "best": { "type": [ "object", "null" ], "description": "The cadence that earned the most engagement per post", "properties": { "band": { "type": "string", "enum": [ "under_3", "3_5", "6_10", "over_10" ] }, "label": { "type": "string" }, "avg_engagements_per_post": { "type": "number" } } } }, "required": [ "days", "weeks", "bands", "best" ] }, "PostTimelineResponse": { "type": "object", "properties": { "post_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Null when the post was made natively on the network" }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" }, "external_post_id": { "type": "string" }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "points": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time" }, "age_minutes": { "type": [ "integer", "null" ] }, "impressions": { "type": [ "integer", "null" ] }, "reach": { "type": [ "integer", "null" ] }, "engagements": { "type": [ "integer", "null" ] }, "likes": { "type": [ "integer", "null" ] }, "comments": { "type": [ "integer", "null" ] }, "shares": { "type": [ "integer", "null" ] }, "video_views": { "type": [ "integer", "null" ] }, "delta": { "type": "object", "properties": { "impressions": { "type": "integer" }, "reach": { "type": "integer" }, "engagements": { "type": "integer" }, "likes": { "type": "integer" }, "comments": { "type": "integer" }, "shares": { "type": "integer" } }, "description": "Movement since the previous point" } } } } } } } }, "required": [ "post_id", "deliveries" ] }, "AnalyticsChangesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "external_post_id": { "type": "string" }, "post_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Null for a post made natively on the network" }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "fetched_at": { "type": "string", "format": "date-time" }, "impressions": { "type": [ "integer", "null" ] }, "reach": { "type": [ "integer", "null" ] }, "engagements": { "type": [ "integer", "null" ] }, "likes": { "type": [ "integer", "null" ] }, "comments": { "type": [ "integer", "null" ] }, "shares": { "type": [ "integer", "null" ] } } } }, "meta": { "$ref": "#/components/schemas/CursorMeta", "description": "Pass `next_cursor` back as `since` to continue; it is null when nothing changed" }, "since": { "type": "string", "format": "date-time", "description": "The `since` instant this page was read from" } }, "required": [ "data", "meta", "since" ] }, "CollectPostResponse": { "type": "object", "properties": { "collected": { "type": "integer", "description": "Deliveries whose metrics were refreshed" }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "external_post_id": { "type": "string" }, "collected": { "type": "boolean" }, "fetched_at": { "type": [ "string", "null" ], "format": "date-time" }, "message": { "type": [ "string", "null" ], "description": "Why the refresh did not happen" } } } } }, "required": [ "collected", "deliveries" ] }, "NativePost": { "type": "object", "properties": { "external_post_id": { "type": "string" }, "text": { "type": [ "string", "null" ] }, "permalink": { "type": [ "string", "null" ] }, "thumbnail_url": { "type": [ "string", "null" ] }, "media_type": { "type": [ "string", "null" ] }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "fetched_at": { "type": "string", "format": "date-time" }, "metrics": { "type": "object", "properties": { "impressions": { "type": [ "integer", "null" ] }, "reach": { "type": [ "integer", "null" ] }, "engagements": { "type": [ "integer", "null" ] }, "likes": { "type": [ "integer", "null" ] }, "comments": { "type": [ "integer", "null" ] }, "shares": { "type": [ "integer", "null" ] }, "video_views": { "type": [ "integer", "null" ] } } } } }, "NativePostListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NativePost" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "CollectSummaryResponse": { "type": "object", "properties": { "accounts": { "type": "integer", "description": "Accounts refreshed" }, "posts": { "type": "integer", "description": "Post metrics collected" }, "demographics": { "type": "integer" }, "errors": { "type": "integer" }, "error_details": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" }, "stage": { "type": "string", "enum": [ "account", "demographics", "timeline", "post" ] }, "message": { "type": "string" }, "action": { "type": "string", "enum": [ "reconnect", "grant", "fund" ], "description": "What fixes it: reconnect the account, grant access, or add funds" } } }, "description": "Only failures the user can act on are listed" } }, "required": [ "accounts", "posts", "demographics", "errors", "error_details" ] }, "PlatformMetricRow": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string", "enum": [ "count", "duration_ms", "currency_usd", "ratio", "series" ] }, "value": {} } }, "AccountPlatformMetricsResponse": { "type": "object", "properties": { "platform": { "type": "string" }, "account": { "type": "object", "properties": { "fetched_at": { "type": [ "string", "null" ], "format": "date-time" }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/PlatformMetricRow" } } } }, "post": { "type": "object", "properties": { "external_post_id": { "type": [ "string", "null" ] }, "fetched_at": { "type": [ "string", "null" ], "format": "date-time" }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/PlatformMetricRow" } } } } }, "required": [ "platform", "account", "post" ] }, "AccountAnalyticsHistoryResponse": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" }, "history": { "type": "array", "items": { "type": "object", "properties": { "followers": { "type": [ "integer", "null" ] }, "following": { "type": [ "integer", "null" ] }, "total_posts": { "type": [ "integer", "null" ] }, "reach": { "type": [ "integer", "null" ] }, "profile_views": { "type": [ "integer", "null" ] }, "fetched_at": { "type": "string", "format": "date-time" } } } } }, "required": [ "account_id", "platform", "username", "history" ] }, "AutomationStep": { "type": "object", "properties": { "position": { "type": "integer" }, "node_id": { "type": "string" }, "action_type": { "type": "string", "enum": [ "generate", "transform", "delay", "publish", "condition", "set_variable", "webhook", "ab_split", "ai", "send_message", "wait_for_reply", "handoff", "add_label", "remove_label", "end" ] }, "action_config": { "type": "object", "additionalProperties": true } } }, "WorkflowNode": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "trigger", "generate", "transform", "delay", "publish", "condition", "set_variable", "webhook", "ab_split", "ai", "send_message", "wait_for_reply", "handoff", "add_label", "remove_label", "end" ] }, "label": { "type": [ "string", "null" ] }, "config": { "type": "object", "additionalProperties": true, "description": "Node settings, echoed back exactly as authored" }, "position": { "type": "integer" }, "layout": { "type": [ "object", "null" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" } } } } }, "WorkflowEdge": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string" }, "source_handle": { "type": [ "string", "null" ] }, "target": { "type": "string" } } }, "WorkflowGraph": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowNode" } }, "edges": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowEdge" } } } }, "Automation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": [ "string", "null" ], "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "trigger_type": { "type": "string", "enum": [ "content_created", "cross_post", "rss_feed", "api_webhook", "schedule", "competitor_post", "post_outperformed", "inbox_topic", "inbox_message", "radar_mention" ] }, "trigger_config": { "type": "object", "additionalProperties": true }, "active": { "type": "boolean" }, "schedule_window": { "type": [ "object", "null" ], "properties": { "days": { "type": "array", "items": { "type": "integer" } }, "start": { "type": "string" }, "end": { "type": "string" } }, "description": "Wall-clock window (workspace timezone) runs may act in; null is unrestricted" }, "max_per_day": { "type": [ "object", "null" ], "additionalProperties": { "type": "integer" }, "description": "Daily caps; null is unrestricted" }, "credit_ceiling": { "type": [ "integer", "null" ], "description": "Max AI credits one unattended run may spend" }, "approval_mode": { "type": "boolean", "description": "Generated posts go through the approval queue" }, "last_triggered_at": { "type": [ "string", "null" ], "format": "date-time" }, "run_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AutomationCreated": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "trigger_type": { "type": "string", "enum": [ "content_created", "cross_post", "rss_feed", "api_webhook", "schedule", "competitor_post", "post_outperformed", "inbox_topic", "inbox_message", "radar_mention" ] }, "trigger_config": { "type": "object", "additionalProperties": true }, "active": { "type": "boolean" }, "schedule_window": { "type": [ "object", "null" ], "properties": { "days": { "type": "array", "items": { "type": "integer" } }, "start": { "type": "string" }, "end": { "type": "string" } } }, "max_per_day": { "type": [ "object", "null" ], "additionalProperties": { "type": "integer" } }, "credit_ceiling": { "type": [ "integer", "null" ] }, "approval_mode": { "type": "boolean" }, "secret": { "type": "string", "description": "Secret for the webhook trigger endpoint (`x-automation-secret` header). Returned only on creation." }, "graph": { "$ref": "#/components/schemas/WorkflowGraph" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationStep" }, "description": "The non-trigger nodes in stored order; the list view of `graph`." }, "created_at": { "type": "string", "format": "date-time" } } }, "AutomationDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": [ "string", "null" ], "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "trigger_type": { "type": "string", "enum": [ "content_created", "cross_post", "rss_feed", "api_webhook", "schedule", "competitor_post", "post_outperformed", "inbox_topic", "inbox_message", "radar_mention" ] }, "trigger_config": { "type": "object", "additionalProperties": true }, "active": { "type": "boolean" }, "schedule_window": { "type": [ "object", "null" ], "properties": { "days": { "type": "array", "items": { "type": "integer" } }, "start": { "type": "string" }, "end": { "type": "string" } } }, "max_per_day": { "type": [ "object", "null" ], "additionalProperties": { "type": "integer" } }, "credit_ceiling": { "type": [ "integer", "null" ] }, "approval_mode": { "type": "boolean" }, "last_triggered_at": { "type": [ "string", "null" ], "format": "date-time" }, "run_count": { "type": "integer" }, "graph": { "$ref": "#/components/schemas/WorkflowGraph" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationStep" }, "description": "The non-trigger nodes in stored order; the list view of `graph`." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AutomationUpdated": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": [ "string", "null" ], "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "trigger_type": { "type": "string", "enum": [ "content_created", "cross_post", "rss_feed", "api_webhook", "schedule", "competitor_post", "post_outperformed", "inbox_topic", "inbox_message", "radar_mention" ] }, "trigger_config": { "type": "object", "additionalProperties": true }, "active": { "type": "boolean" }, "schedule_window": { "type": [ "object", "null" ], "properties": { "days": { "type": "array", "items": { "type": "integer" } }, "start": { "type": "string" }, "end": { "type": "string" } } }, "max_per_day": { "type": [ "object", "null" ], "additionalProperties": { "type": "integer" } }, "credit_ceiling": { "type": [ "integer", "null" ] }, "approval_mode": { "type": "boolean" }, "graph": { "$ref": "#/components/schemas/WorkflowGraph" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationStep" }, "description": "The non-trigger nodes in stored order; the list view of `graph`." }, "updated_at": { "type": "string", "format": "date-time" } } }, "AutomationRun": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string", "description": "running, deferred, waiting (parked on a Wait for Reply node), completed, failed or cancelled" }, "current_step": { "type": [ "integer", "null" ] }, "trigger_event": { "type": [ "object", "null" ], "additionalProperties": true }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_message": { "type": [ "string", "null" ] }, "deferred_until": { "type": [ "string", "null" ], "format": "date-time" }, "defer_reason": { "type": [ "string", "null" ], "description": "`outside_window` or `daily_cap`" }, "defer_detail": { "type": [ "string", "null" ] }, "defer_count": { "type": "integer" }, "replay_of_run_id": { "type": [ "integer", "null" ], "description": "The run this one replays, when it is a replay" } } }, "AutomationRunDetail": { "type": "object", "properties": { "id": { "type": "integer" }, "automation_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "current_step": { "type": [ "integer", "null" ] }, "current_node_id": { "type": [ "string", "null" ] }, "waiting_until": { "type": [ "string", "null" ], "format": "date-time", "description": "When a waiting run gives up on the reply" }, "trigger_event": { "type": [ "object", "null" ], "additionalProperties": true }, "context": { "type": [ "object", "null" ], "additionalProperties": true }, "initial_context": { "type": [ "object", "null" ], "additionalProperties": true, "description": "The context before the first step; what a replay re-runs against" }, "replay_of_run_id": { "type": [ "integer", "null" ] }, "deferred_until": { "type": [ "string", "null" ], "format": "date-time" }, "defer_reason": { "type": [ "string", "null" ], "description": "`outside_window` or `daily_cap`" }, "defer_detail": { "type": [ "string", "null" ] }, "defer_count": { "type": "integer" }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_message": { "type": [ "string", "null" ] }, "logs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "step_position": { "type": "integer" }, "node_id": { "type": [ "string", "null" ] }, "handle": { "type": [ "string", "null" ], "description": "The output the run left the node through" }, "status": { "type": "string" }, "input_snapshot": { "type": [ "object", "null" ], "additionalProperties": true }, "output_snapshot": { "type": [ "object", "null" ], "additionalProperties": true }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "duration_ms": { "type": [ "integer", "null" ] }, "error_message": { "type": [ "string", "null" ] } } } } } }, "AutomationStatsResponse": { "type": "object", "properties": { "total_automations": { "type": "integer" }, "active_automations": { "type": "integer" }, "total_runs_24h": { "type": "integer", "description": "Runs started in the last 24 hours" }, "runs_by_status": { "type": "object", "additionalProperties": { "type": "integer" } }, "recent_runs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "automation_id": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } } } } }, "required": [ "total_automations", "active_automations", "total_runs_24h", "runs_by_status", "recent_runs" ] }, "InboxAccountRef": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" }, "name": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } } }, "InboxAttachment": { "type": "object", "properties": { "kind": { "type": "string", "description": "`image`, `video`, `audio`, `file`, `link` or `share`" }, "name": { "type": [ "string", "null" ] }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "link": { "type": [ "string", "null" ], "description": "The target of a `link` attachment" }, "url": { "type": [ "string", "null" ], "description": "Served by `GET /v1/inbox/{id}/attachments/{index}`, never a platform URL" }, "preview_url": { "type": [ "string", "null" ] } } }, "InboxPostContext": { "type": [ "object", "null" ], "description": "The platform post the item sits under, whoever published it", "properties": { "external_id": { "type": [ "string", "null" ] }, "is_own": { "type": "boolean", "description": "Published from one of our accounts" }, "text": { "type": [ "string", "null" ] }, "author_name": { "type": [ "string", "null" ] }, "author_handle": { "type": [ "string", "null" ] }, "author_avatar_url": { "type": [ "string", "null" ] }, "thumbnail_url": { "type": [ "string", "null" ] }, "permalink": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "published": { "type": [ "object", "null" ], "description": "The FoPost post this was published from, when it was", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": [ "string", "null" ] } } } } }, "InboxItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Present on list rows" }, "platform": { "type": "string" }, "type": { "type": "string", "enum": [ "comment", "mention", "dm", "review" ] }, "state": { "type": "string", "enum": [ "unread", "read", "resolved", "snoozed" ] }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "conversation_id": { "type": [ "string", "null" ] }, "author_name": { "type": [ "string", "null" ] }, "author_handle": { "type": [ "string", "null" ] }, "author_avatar_url": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] }, "rating": { "type": [ "integer", "null" ], "description": "Stars on a review, 1-5. Null on every other type" }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/InboxAttachment" } }, "permalink": { "type": [ "string", "null" ] }, "post_external_id": { "type": [ "string", "null" ] }, "parent_external_id": { "type": [ "string", "null" ] }, "platform_created_at": { "type": [ "string", "null" ], "format": "date-time" }, "snoozed_until": { "type": [ "string", "null" ], "format": "date-time" }, "replied_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "can_reply": { "type": "boolean", "description": "False on platforms whose API reads but cannot answer" }, "hidden": { "type": "boolean" }, "liked": { "type": "boolean" }, "pinned": { "type": "boolean" }, "reaction": { "type": [ "string", "null" ], "description": "Our reaction on a DM" }, "edited_at": { "type": [ "string", "null" ], "format": "date-time" }, "moderation_status": { "type": [ "string", "null" ], "description": "The platform's own moderation state, where it reports one: `published`, `held`, `spam` or `rejected`" }, "can_hide": { "type": "boolean" }, "can_delete": { "type": "boolean", "description": "A comment someone left, or our own reply" }, "can_like": { "type": "boolean" }, "can_pin": { "type": "boolean", "description": "Our own comment only" }, "can_edit": { "type": "boolean", "description": "Our own comment only" }, "can_react": { "type": "boolean" }, "can_send_media": { "type": "boolean" }, "can_quick_reply": { "type": "boolean" }, "can_private_reply": { "type": "boolean", "description": "A DM can be opened with `POST /v1/inbox/conversations` and `comment_id`" }, "post": { "type": [ "object", "null" ], "description": "The FoPost post this item was left under, when we published it", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": [ "string", "null" ] } } }, "post_context": { "$ref": "#/components/schemas/InboxPostContext" }, "raw": { "type": [ "object", "null" ], "additionalProperties": true, "description": "The platform's message object as stored; only with `include_raw=1` on one workspace, for a bypassed user" }, "account": { "$ref": "#/components/schemas/InboxAccountRef" } } }, "ContactChannel": { "type": "object", "properties": { "platform": { "type": "string" }, "handle": { "type": "string", "description": "Lower-cased, no leading @" }, "externalId": { "type": [ "string", "null" ], "description": "The platform's own id for this person, when known" } }, "required": [ "platform", "handle" ] }, "Contact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "display_name": { "type": [ "string", "null" ] }, "channels": { "type": "array", "items": { "$ref": "#/components/schemas/ContactChannel" } }, "source": { "type": "string", "enum": [ "inbox", "radar", "import" ] }, "note": { "type": [ "string", "null" ] }, "first_seen_at": { "type": "string", "format": "date-time" }, "last_seen_at": { "type": "string", "format": "date-time" }, "fields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom field values, keyed by field key" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string" } } } }, "workspace_id": { "type": "string", "format": "uuid", "description": "Only on a listing that spans workspaces" } }, "required": [ "id", "channels", "source", "first_seen_at", "last_seen_at", "fields" ] }, "ContactListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "CreateContactRequest": { "type": "object", "properties": { "workspace_id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" }, "channels": { "type": "array", "items": { "$ref": "#/components/schemas/ContactChannel" } }, "note": { "type": "string" }, "fields": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "workspace_id", "channels" ] }, "UpdateContactRequest": { "type": "object", "properties": { "display_name": { "type": [ "string", "null" ] }, "channels": { "type": "array", "items": { "$ref": "#/components/schemas/ContactChannel" } }, "note": { "type": [ "string", "null" ] }, "fields": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] }, "description": "A null or empty value clears that field" } } }, "AudienceFilter": { "type": "object", "properties": { "platforms": { "type": "array", "items": { "type": "string" } }, "label_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "source": { "type": "string", "enum": [ "inbox", "radar", "import" ] }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "op": { "type": "string", "enum": [ "is", "is_not", "contains", "is_set", "is_not_set" ] }, "value": { "type": "string" } }, "required": [ "key" ] } } }, "description": "Who a broadcast or enrollment resolves to. Every clause narrows: a contact has to match all of them." }, "BroadcastCounts": { "type": "object", "properties": { "total": { "type": "integer" }, "sent": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" }, "pending": { "type": "integer" } }, "required": [ "total", "sent", "skipped", "failed", "pending" ] }, "BlogArticleImage": { "type": "object", "properties": { "media_id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "alt": { "type": "string" }, "position": { "type": "integer", "description": "Index of the outline heading the image sits under; absent on the featured image" } }, "required": [ "media_id", "url", "alt" ] }, "BlogSettings": { "type": "object", "properties": { "site_url": { "type": [ "string", "null" ] }, "topic": { "type": [ "string", "null" ] }, "audience": { "type": [ "string", "null" ] }, "language": { "type": "string" }, "location_code": { "type": "integer" }, "cadence_per_week": { "type": "integer", "description": "Articles planned per week; 0 turns planning off" }, "review_hold_days": { "type": "integer", "description": "Days a draft waits for review before it may auto-publish" }, "auto_publish": { "type": "boolean" }, "image_tier": { "type": "string", "enum": [ "draft", "standard", "best" ] }, "in_body_images": { "type": "integer" }, "min_words": { "type": "integer" }, "max_words": { "type": "integer" }, "brand_voice_id": { "type": [ "string", "null" ], "format": "uuid" }, "target_kind": { "type": [ "string", "null" ], "enum": [ "product_blog", "account", "website", null ] }, "target_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "target_platform": { "type": [ "string", "null" ] }, "website_url": { "type": [ "string", "null" ] }, "has_website_secret": { "type": "boolean" }, "keyword_data_available": { "type": "boolean", "description": "Whether search volume and difficulty can be fetched on this deployment; on GET only" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "language", "cadence_per_week", "review_hold_days", "auto_publish", "has_website_secret" ] }, "UpdateBlogSettingsRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "siteUrl": { "type": [ "string", "null" ], "format": "uri" }, "topic": { "type": [ "string", "null" ] }, "audience": { "type": [ "string", "null" ] }, "language": { "type": "string" }, "locationCode": { "type": "integer" }, "cadencePerWeek": { "type": "integer", "minimum": 0, "maximum": 7 }, "reviewHoldDays": { "type": "integer", "minimum": 0, "maximum": 14 }, "autoPublish": { "type": "boolean" }, "imageTier": { "type": "string", "enum": [ "draft", "standard", "best" ] }, "inBodyImages": { "type": "integer", "minimum": 0, "maximum": 3 }, "minWords": { "type": "integer" }, "maxWords": { "type": "integer" }, "brandVoiceId": { "type": [ "string", "null" ], "format": "uuid" }, "targetKind": { "type": [ "string", "null" ], "enum": [ "product_blog", "account", "website", null ] }, "targetAccountId": { "type": [ "string", "null" ], "format": "uuid" }, "websiteUrl": { "type": [ "string", "null" ], "format": "uri", "description": "Where published articles are POSTed as a signed webhook; setting it issues a secret, returned once" } }, "required": [ "workspaceId" ] }, "BlogKeyword": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "keyword": { "type": "string" }, "search_volume": { "type": [ "integer", "null" ] }, "difficulty": { "type": [ "integer", "null" ], "description": "0–100" }, "cpc": { "type": [ "number", "null" ] }, "intent": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "provider", "user", "agent" ] }, "status": { "type": "string", "enum": [ "suggested", "planned", "written", "dismissed" ] }, "planned_for": { "type": [ "string", "null" ], "format": "date" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "keyword", "source", "status", "created_at" ] }, "BlogArticle": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "slug": { "type": "string" }, "keyword": { "type": [ "string", "null" ] }, "excerpt": { "type": [ "string", "null" ] }, "meta_title": { "type": [ "string", "null" ] }, "meta_description": { "type": [ "string", "null" ] }, "featured_image": { "oneOf": [ { "$ref": "#/components/schemas/BlogArticleImage" }, { "type": "null" } ] }, "tags": { "type": "array", "items": { "type": "string" } }, "word_count": { "type": "integer" }, "status": { "type": "string", "enum": [ "queued", "writing", "draft", "scheduled", "publishing", "published", "failed", "rejected" ] }, "origin": { "type": "string", "enum": [ "plan", "user", "agent" ] }, "review_until": { "type": [ "string", "null" ], "format": "date-time" }, "publish_at": { "type": [ "string", "null" ], "format": "date-time" }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "published_url": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "slug", "tags", "word_count", "status", "origin", "created_at", "updated_at" ] }, "BlogArticleFull": { "allOf": [ { "$ref": "#/components/schemas/BlogArticle" }, { "type": "object", "properties": { "instructions": { "type": [ "string", "null" ] }, "outline": { "type": "array", "items": { "type": "string" } }, "brief": { "type": [ "object", "null" ], "description": "The research the writer worked from", "properties": { "competitors": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "description": { "type": "string" } } } }, "questions": { "type": "array", "items": { "type": "string" } }, "search_volume": { "type": [ "integer", "null" ] }, "difficulty": { "type": [ "integer", "null" ] } } }, "body_markdown": { "type": "string" }, "body_html": { "type": "string" }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/BlogArticleImage" } } } } ] }, "CreateBlogArticleRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "keyword": { "type": "string" }, "keywordId": { "type": "string", "format": "uuid", "description": "A keyword from the plan; its term becomes the target" }, "instructions": { "type": "string", "maxLength": 4000 } }, "required": [ "workspaceId" ], "description": "One of title, keyword or keywordId is required" }, "UpdateBlogArticleRequest": { "type": "object", "properties": { "title": { "type": "string" }, "slug": { "type": "string", "pattern": "^[a-z0-9-]+$" }, "excerpt": { "type": [ "string", "null" ] }, "metaTitle": { "type": [ "string", "null" ] }, "metaDescription": { "type": [ "string", "null" ] }, "bodyMarkdown": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "publishAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Puts the draft on the calendar; null returns it to review" } } }, "Broadcast": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "text": { "type": "string" }, "account_id": { "type": [ "string", "null" ] }, "audience": { "$ref": "#/components/schemas/AudienceFilter" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "sending", "sent", "cancelled" ] }, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "counts": { "$ref": "#/components/schemas/BroadcastCounts" }, "workspace_id": { "type": "string", "format": "uuid", "description": "Only on a listing that spans workspaces" } }, "required": [ "id", "name", "text", "status", "created_at" ] }, "BroadcastListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Broadcast" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "CreateBroadcastRequest": { "type": "object", "properties": { "workspace_id": { "type": "string", "format": "uuid" }, "account_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "text": { "type": "string" }, "media_id": { "type": "string", "format": "uuid" }, "audience": { "$ref": "#/components/schemas/AudienceFilter" }, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "workspace_id", "account_id", "name", "text" ] }, "UpdateBroadcastRequest": { "type": "object", "properties": { "name": { "type": "string" }, "text": { "type": "string" }, "media_id": { "type": "string", "format": "uuid" }, "audience": { "$ref": "#/components/schemas/AudienceFilter" }, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "BroadcastRecipient": { "type": "object", "properties": { "contact_id": { "type": "string", "format": "uuid" }, "display_name": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "sent", "skipped", "failed" ] }, "skip_reason": { "type": [ "string", "null" ], "enum": [ "window_closed", "no_conversation", "unsupported_platform", null ], "description": "Why nothing was sent. `window_closed` means the network’s messaging window had shut, so the message was never attempted." }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "error": { "type": [ "string", "null" ] } }, "required": [ "contact_id", "status" ] }, "BroadcastRecipientListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BroadcastRecipient" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "SequenceStep": { "type": "object", "properties": { "delay_hours": { "type": "number", "description": "Wait this long after the previous step" }, "text": { "type": "string" }, "media_id": { "type": "string", "format": "uuid" } }, "required": [ "delay_hours", "text" ] }, "Sequence": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "account_id": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/SequenceStep" } }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "created_at": { "type": "string", "format": "date-time" }, "enrollments": { "type": "object", "properties": { "total": { "type": "integer" }, "active": { "type": "integer" }, "completed": { "type": "integer" }, "stopped": { "type": "integer" }, "failed": { "type": "integer" } }, "required": [ "total", "active", "completed", "stopped", "failed" ] }, "workspace_id": { "type": "string", "format": "uuid", "description": "Only on a listing that spans workspaces" } }, "required": [ "id", "name", "steps", "status", "created_at" ] }, "SequenceListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Sequence" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "CreateSequenceRequest": { "type": "object", "properties": { "workspace_id": { "type": "string", "format": "uuid" }, "account_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/SequenceStep" } }, "status": { "type": "string", "enum": [ "active", "paused" ] } }, "required": [ "workspace_id", "account_id", "name", "steps" ] }, "UpdateSequenceRequest": { "type": "object", "properties": { "name": { "type": "string" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/SequenceStep" } }, "status": { "type": "string", "enum": [ "active", "paused" ] } } }, "EnrollRequest": { "type": "object", "properties": { "contact_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "audience": { "$ref": "#/components/schemas/AudienceFilter" } }, "description": "Name contacts outright, or the audience they are drawn from." }, "UnenrollRequest": { "type": "object", "properties": { "contact_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "contact_ids" ] }, "Enrollment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "contact_id": { "type": "string", "format": "uuid" }, "display_name": { "type": [ "string", "null" ] }, "step": { "type": "integer", "description": "Steps already sent, so also the index of the next one" }, "next_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "enum": [ "active", "completed", "stopped", "failed" ] }, "last_sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "error": { "type": [ "string", "null" ] } }, "required": [ "id", "contact_id", "step", "status" ] }, "EnrollmentListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Enrollment" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "ContactConversation": { "type": "object", "properties": { "key": { "type": "string", "description": "DM thread id, else the root post id, else the handle" }, "account_id": { "type": "string", "format": "uuid" }, "account_username": { "type": [ "string", "null" ] }, "platform": { "type": "string" }, "messages": { "type": "integer" }, "received": { "type": "integer" }, "sent": { "type": "integer" }, "last_message_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_item_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The newest inbox item in the thread" } }, "required": [ "key", "account_id", "platform", "messages", "received", "sent" ] }, "ImportContactsRequest": { "type": "object", "properties": { "workspace_id": { "type": "string", "format": "uuid" }, "csv": { "type": "string", "description": "CSV text. `platform` and `handle` are required columns; `external_id`, `display_name` and `note` are optional, and any other column is read as a custom field key." } }, "required": [ "workspace_id", "csv" ] }, "ImportContactsResponse": { "type": "object", "properties": { "created": { "type": "integer" }, "merged": { "type": "integer", "description": "Rows that folded into a contact already on file" }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": "integer" }, "reason": { "type": "string" } }, "required": [ "row", "reason" ] } }, "unknown_columns": { "type": "array", "items": { "type": "string" }, "description": "Columns that named neither a reserved field nor a custom field" } }, "required": [ "created", "merged", "skipped", "unknown_columns" ] }, "CustomField": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string", "description": "Lower-case key; also the CSV column header" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "number", "date", "select", "boolean" ] }, "options": { "type": "array", "items": { "type": "string" }, "description": "Allowed values when `type` is select" }, "position": { "type": "integer" } }, "required": [ "id", "key", "name", "type", "options", "position" ] }, "CreateCustomFieldRequest": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "number", "date", "select", "boolean" ] }, "options": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "name" ] }, "UpdateCustomFieldRequest": { "type": "object", "properties": { "name": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" } }, "position": { "type": "integer" } } }, "ConversationAnalyticsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "An opaque, stable handle for the thread. It is a keyed digest, not the thread id or handle it groups on, so rows stay correlatable across pages without carrying who wrote them." }, "account_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "received": { "type": "integer" }, "sent": { "type": "integer" }, "answered": { "type": "integer" }, "open": { "type": "integer" }, "median_response_minutes": { "type": [ "number", "null" ], "description": "Median minutes to the first reply in this thread" }, "first_message_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_message_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "key", "account_id", "platform", "received", "sent" ] } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "InboxListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InboxItem" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "InboxThread": { "type": "object", "properties": { "workspace_id": { "type": [ "string", "null" ], "format": "uuid" }, "account_id": { "type": "string", "format": "uuid" }, "post_external_id": { "type": [ "string", "null" ] }, "comment_count": { "type": "integer" }, "unread_count": { "type": "integer" }, "last_comment_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_comment_text": { "type": [ "string", "null" ] }, "last_comment_author": { "type": [ "string", "null" ] }, "rating": { "type": [ "integer", "null" ], "description": "Stars, on a review thread. Null on comments and mentions" }, "post": { "$ref": "#/components/schemas/InboxPostContext" }, "account": { "$ref": "#/components/schemas/InboxAccountRef" } } }, "InboxThreadListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InboxThread" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "InboxConversation": { "type": "object", "properties": { "workspace_id": { "type": [ "string", "null" ], "format": "uuid" }, "account_id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": "string" }, "message_count": { "type": "integer" }, "unread_count": { "type": "integer" }, "last_message_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_message_text": { "type": [ "string", "null" ] }, "last_message_outbound": { "type": "boolean" }, "participant": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "handle": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] } } }, "account": { "$ref": "#/components/schemas/InboxAccountRef" } } }, "InboxConversationListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InboxConversation" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "KnowledgeSource": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "faq", "text", "url", "file" ], "description": "Where the text comes from" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "syncing", "ready", "failed" ], "description": "Only a `ready` source is searched" }, "status_message": { "type": [ "string", "null" ], "description": "Why the last sync failed, in plain words" }, "url": { "type": [ "string", "null" ], "description": "For `url` sources" }, "media_id": { "type": [ "string", "null" ], "format": "uuid", "description": "For `file` sources" }, "brand_voice_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Null means the source serves the whole workspace" }, "chunk_count": { "type": "integer", "description": "Searchable passages the last sync produced" }, "content": { "type": [ "string", "null" ], "description": "The typed text, for `faq` and `text` sources only" }, "last_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "kind", "title", "status", "chunk_count", "created_at", "updated_at" ] }, "KnowledgeMatch": { "type": "object", "properties": { "source_id": { "type": "string", "format": "uuid" }, "source_title": { "type": "string" }, "source_kind": { "type": "string", "enum": [ "faq", "text", "url", "file" ] }, "source_url": { "type": [ "string", "null" ] }, "text": { "type": "string", "description": "The passage, as stored" }, "score": { "type": "number", "description": "Similarity to the question, 0–1" } }, "required": [ "source_id", "source_title", "source_kind", "text", "score" ] }, "InboxAccount": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": [ "string", "null" ], "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" }, "name": { "type": "string" }, "avatar": { "type": [ "string", "null" ] }, "inbox_supported": { "type": "boolean", "description": "Comments and mentions can be read for this account" }, "pending_reason": { "type": [ "string", "null" ] }, "dm_supported": { "type": "boolean" }, "dm_pending_reason": { "type": [ "string", "null" ] }, "can_start_conversation": { "type": "boolean", "description": "A new DM can be opened from this account by handle" }, "reconnect_required": { "type": "boolean", "description": "The grant predates a permission the inbox read needs; reconnect the account" } } }, "InboxPlatform": { "type": "object", "properties": { "platform": { "type": "string" }, "comments": { "type": "string", "enum": [ "live", "soon", "none" ] }, "dms": { "type": "string", "enum": [ "live", "soon", "none" ] } } }, "InboxApproval": { "type": "object", "properties": { "id": { "type": "integer", "description": "Approval id, used by the approve and reject routes" }, "workspace_id": { "type": [ "string", "null" ], "format": "uuid" }, "source": { "type": "string", "description": "What drafted the reply: an automation or the agent" }, "reply": { "type": "string", "description": "The drafted text" }, "created_at": { "type": "string", "format": "date-time" }, "item": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "type": { "type": "string" }, "state": { "type": "string" }, "author_name": { "type": [ "string", "null" ] }, "author_handle": { "type": [ "string", "null" ] }, "author_avatar_url": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] }, "permalink": { "type": [ "string", "null" ] }, "platform_created_at": { "type": [ "string", "null" ], "format": "date-time" } } } } }, "InboxReplyResponse": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/InboxItem" }, "reply": { "type": "object", "properties": { "external_id": { "type": [ "string", "null" ] }, "external_url": { "type": [ "string", "null" ] } } } } }, "InboxRefreshResponse": { "type": "object", "properties": { "accounts_polled": { "type": "integer" }, "new_items": { "type": "integer" }, "rate_limited": { "type": "integer", "description": "Accounts the platform rate-limited during this poll" }, "dm_reconnect": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "account": { "type": "string" } } } } } }, "AdTargeting": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "string" } }, "ageMin": { "type": "integer" }, "ageMax": { "type": "integer" }, "gender": { "type": "string", "enum": [ "all", "male", "female" ] }, "audienceIds": { "type": "array", "items": { "type": "string" } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "region", "city", "zip", "geo_market" ] } } } }, "interests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } }, "behaviors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } }, "income": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } }, "AdInsights": { "type": [ "object", "null" ], "properties": { "impressions": { "type": "integer" }, "reach": { "type": "integer" }, "clicks": { "type": "integer" }, "spendMinor": { "type": "integer", "description": "Account currency, minor units" } } }, "Ad": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "boost", "ad" ] }, "name": { "type": "string" }, "goal": { "type": "string", "enum": [ "engagement", "traffic", "awareness", "video_views" ] }, "status": { "type": "string", "description": "What was asked for: `active` or `paused`" }, "effectiveStatus": { "type": [ "string", "null" ], "description": "Meta's own delivery status, from the last refresh" }, "connectionId": { "type": [ "string", "null" ], "format": "uuid" }, "accountId": { "type": [ "string", "null" ], "format": "uuid", "description": "The connected account a boost was built from" }, "platform": { "type": [ "string", "null" ] }, "adAccountId": { "type": "string" }, "sourcePostId": { "type": [ "string", "null" ], "format": "uuid", "description": "The FoPost post a boost promotes" }, "budgetMinor": { "type": "integer" }, "budgetType": { "type": "string", "enum": [ "daily", "lifetime" ] }, "currency": { "type": [ "string", "null" ] }, "endAt": { "type": [ "string", "null" ], "format": "date-time" }, "targeting": { "$ref": "#/components/schemas/AdTargeting" }, "creative": { "type": [ "object", "null" ], "properties": { "text": { "type": "string" }, "headline": { "type": "string" }, "destinationUrl": { "type": "string" }, "mediaUrl": { "type": "string" }, "urlTags": { "type": "string" } } }, "insights": { "$ref": "#/components/schemas/AdInsights" }, "insightsAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "AdConnection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "description": "`meta`" }, "authType": { "type": "string", "description": "`business` or `user`" }, "name": { "type": "string" }, "businessId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "workspaceId": { "type": "string", "format": "uuid" } } }, "PinterestBoard": { "type": "object", "properties": { "id": { "type": "string", "description": "Pinterest board id" }, "name": { "type": "string" }, "privacy": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ], "description": "Board cover image" } }, "required": [ "id", "name" ] }, "YouTubePlaylist": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "privacy": { "type": [ "string", "null" ] }, "item_count": { "type": [ "integer", "null" ] }, "thumbnail_url": { "type": [ "string", "null" ] }, "is_default": { "type": "boolean", "description": "The playlist a new video joins when none is picked" } }, "required": [ "id", "title", "is_default" ] }, "YouTubeCaptionTrack": { "type": "object", "properties": { "id": { "type": "string" }, "language": { "type": "string", "description": "BCP-47 tag" }, "name": { "type": "string" }, "track_kind": { "type": [ "string", "null" ] }, "is_draft": { "type": "boolean" }, "is_auto_synced": { "type": "boolean" }, "last_updated": { "type": [ "string", "null" ] } }, "required": [ "id", "language", "name" ] }, "YouTubeTranscript": { "type": "object", "properties": { "caption_id": { "type": "string" }, "transcript": { "type": "string", "description": "The track as SRT" } }, "required": [ "caption_id", "transcript" ] }, "BlueskyLanguages": { "type": "object", "properties": { "languages": { "type": "array", "items": { "type": "string", "description": "BCP-47 tag" } } }, "required": [ "languages" ] }, "TikTokCreatorInfo": { "type": "object", "properties": { "username": { "type": [ "string", "null" ] }, "nickname": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] }, "privacy_level_options": { "type": "array", "items": { "type": "string" }, "description": "Privacy levels this creator may publish at right now" }, "comment_disabled": { "type": "boolean" }, "duet_disabled": { "type": "boolean" }, "stitch_disabled": { "type": "boolean" }, "max_video_post_duration_sec": { "type": [ "integer", "null" ] } }, "required": [ "privacy_level_options" ] }, "InstagramAudio": { "type": "object", "properties": { "id": { "type": "string", "description": "Pass as the audio_id platform setting on a Reel" }, "title": { "type": [ "string", "null" ] }, "artist": { "type": [ "string", "null" ] }, "duration_ms": { "type": [ "integer", "null" ] }, "audio_type": { "type": [ "string", "null" ] }, "cover_artwork_url": { "type": [ "string", "null" ] }, "preview_url": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "is_ads_eligible": { "type": [ "boolean", "null" ] } }, "required": [ "id" ] }, "InstagramPublishingLimit": { "type": "object", "properties": { "quota_usage": { "type": "integer", "description": "Containers published in the window" }, "quota_total": { "type": [ "integer", "null" ] }, "quota_duration_sec": { "type": [ "integer", "null" ] }, "remaining": { "type": [ "integer", "null" ] } }, "required": [ "quota_usage" ] }, "InstagramStory": { "type": "object", "properties": { "id": { "type": "string" }, "media_type": { "type": [ "string", "null" ] }, "media_product_type": { "type": [ "string", "null" ] }, "permalink": { "type": [ "string", "null" ] }, "media_url": { "type": [ "string", "null" ] }, "thumbnail_url": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "timestamp": { "type": [ "string", "null" ] }, "insights": { "type": [ "object", "null" ], "additionalProperties": { "type": "integer" }, "description": "Present when asked for; absent for a story too young to report" } }, "required": [ "id" ] }, "InstagramStoryInsights": { "type": "object", "properties": { "story_id": { "type": "string" }, "insights": { "type": "object", "additionalProperties": { "type": "integer" } } }, "required": [ "story_id", "insights" ] }, "LinkedInMention": { "type": "object", "properties": { "urn": { "type": "string" }, "name": { "type": "string" }, "vanity_name": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "annotation": { "type": "string", "description": "Paste into the post text for LinkedIn to render a link" } }, "required": [ "urn", "name", "annotation" ] }, "TikTokMusic": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "author": { "type": [ "string", "null" ] }, "duration_sec": { "type": [ "integer", "null" ] }, "cover_url": { "type": [ "string", "null" ] }, "preview_url": { "type": [ "string", "null" ] } }, "required": [ "id", "title" ] }, "TikTokPlace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "address": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "TikTokVideoSource": { "type": "object", "properties": { "video_id": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "duration_sec": { "type": [ "integer", "null" ] }, "cover_image_url": { "type": [ "string", "null" ] }, "share_url": { "type": [ "string", "null" ] }, "embed_link": { "type": [ "string", "null" ] }, "download_url": { "type": [ "string", "null" ], "description": "The address a repurpose run reads. TikTok's API serves no raw media file, so this is the share URL." } }, "required": [ "video_id" ] }, "SlackChannel": { "type": "object", "properties": { "id": { "type": "string", "description": "Slack channel id" }, "name": { "type": "string" }, "is_private": { "type": "boolean" }, "is_member": { "type": "boolean", "description": "Whether the bot is in the channel" }, "is_current": { "type": "boolean", "description": "The channel this account posts to" } } }, "SlackMember": { "type": "object", "properties": { "id": { "type": "string", "description": "Slack user id; pass it as the handle to start a DM" }, "name": { "type": "string" }, "real_name": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "avatar": { "type": [ "string", "null" ] }, "is_bot": { "type": "boolean" } } }, "DiscordChannel": { "type": "object", "properties": { "id": { "type": "string", "description": "Discord channel id" }, "name": { "type": "string" }, "type": { "type": "integer", "description": "Discord channel type: 0 text, 5 announcement, 15 forum" }, "parent_id": { "type": [ "string", "null" ] }, "nsfw": { "type": "boolean" }, "can_post": { "type": "boolean", "description": "False when a Discord channel permission shuts the bot out; publishing there would fail" }, "is_current": { "type": "boolean", "description": "The channel this account posts to" } } }, "DiscordIdentity": { "type": "object", "properties": { "username": { "type": [ "string", "null" ], "description": "The bot's nickname in this server, or null for its own" }, "avatar_url": { "type": [ "string", "null" ], "description": "Image the bot wears in this server" } } }, "DiscordMessage": { "type": "object", "properties": { "id": { "type": "string" }, "channel_id": { "type": "string" }, "content": { "type": "string" }, "author_id": { "type": "string" }, "author_name": { "type": "string" }, "pinned": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "DiscordScheduledEvent": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "channel_id": { "type": [ "string", "null" ], "description": "Voice or stage channel, or null for an external event" }, "location": { "type": [ "string", "null" ], "description": "Where an external event happens" }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "description": "`scheduled`, `active`, `completed` or `canceled`" }, "user_count": { "type": [ "integer", "null" ] } } }, "DiscordMember": { "type": "object", "properties": { "id": { "type": "string", "description": "Discord user id; pass it as `member_id` to send a DM" }, "username": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "nick": { "type": [ "string", "null" ], "description": "Nickname in this server" }, "avatar": { "type": [ "string", "null" ] }, "is_bot": { "type": "boolean" }, "roles": { "type": "array", "items": { "type": "string" } }, "joined_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "DiscordRole": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "integer", "description": "RGB integer; 0 is the default colour" }, "hoist": { "type": "boolean", "description": "Shown separately in the member list" }, "mentionable": { "type": "boolean" }, "managed": { "type": "boolean", "description": "Owned by an integration; not editable" }, "position": { "type": "integer" }, "permissions": { "type": "string", "description": "Permission bitfield as a decimal string" } } }, "SlackIdentity": { "type": "object", "properties": { "username": { "type": [ "string", "null" ], "description": "Name posts appear under, or null for the app name" }, "icon_url": { "type": [ "string", "null" ], "description": "Image posts appear with" }, "icon_emoji": { "type": [ "string", "null" ], "description": "Emoji code posts appear with, e.g. `:rocket:`" } } }, "AdProvider": { "type": "object", "properties": { "id": { "type": "string", "description": "Ad network id, e.g. `meta`" }, "name": { "type": "string" }, "logo": { "type": "string", "description": "Logo slug" }, "configured": { "type": "boolean", "description": "False while the network is not available to connect" }, "connectMethods": { "type": "array", "items": { "type": "string" }, "description": "Login routes available on this deployment" }, "capabilities": { "type": "object", "additionalProperties": { "type": "boolean" }, "description": "What the network supports: campaigns, boost, audiences, leadForms, and so on" } } }, "GoogleKeyword": { "type": "object", "properties": { "id": { "type": "string", "description": "`~keyword~~`" }, "adGroupId": { "type": "string" }, "text": { "type": "string" }, "matchType": { "type": "string", "enum": [ "EXACT", "PHRASE", "BROAD" ] }, "status": { "type": "string" }, "cpcBidMinor": { "type": [ "integer", "null" ] }, "negative": { "type": "boolean" } } }, "GoogleKeywordIdea": { "type": "object", "properties": { "text": { "type": "string" }, "avgMonthlySearches": { "type": "integer" }, "competition": { "type": [ "string", "null" ] }, "lowTopOfPageBidMinor": { "type": [ "integer", "null" ] }, "highTopOfPageBidMinor": { "type": [ "integer", "null" ] } } }, "GoogleSearchTerm": { "type": "object", "properties": { "term": { "type": "string" }, "adGroupId": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "metrics": { "$ref": "#/components/schemas/InsightsMetrics" } } }, "GoogleBidStrategy": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "campaignCount": { "type": "integer" } } }, "GoogleAdScheduleSlot": { "type": "object", "properties": { "id": { "type": "string" }, "dayOfWeek": { "type": "string" }, "startHour": { "type": "integer" }, "endHour": { "type": "integer" }, "bidModifier": { "type": [ "number", "null" ] } } }, "GoogleSharedSet": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "memberCount": { "type": "integer" } } }, "GoogleAsset": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "text": { "type": [ "string", "null" ], "description": "What a sitelink, callout or snippet renders" }, "finalUrl": { "type": [ "string", "null" ] } } }, "GoogleAssetLink": { "type": "object", "properties": { "id": { "type": "string" }, "assetId": { "type": "string" }, "level": { "type": "string", "enum": [ "customer", "campaign" ] }, "ownerId": { "type": [ "string", "null" ] }, "fieldType": { "type": "string" }, "status": { "type": "string" } } }, "GoogleAssetsResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "assets": { "type": "array", "items": { "$ref": "#/components/schemas/GoogleAsset" } }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/GoogleAssetLink" } } } } }, "required": [ "data" ] }, "GoogleAssetGroup": { "type": "object", "properties": { "id": { "type": "string" }, "campaignId": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "finalUrls": { "type": "array", "items": { "type": "string" } } } }, "GoogleRecommendation": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "campaignId": { "type": [ "string", "null" ] }, "adGroupId": { "type": [ "string", "null" ] }, "dismissed": { "type": "boolean" }, "impact": { "type": "object", "properties": { "baseClicks": { "type": [ "number", "null" ] }, "potentialClicks": { "type": [ "number", "null" ] }, "baseCostMinor": { "type": [ "number", "null" ] }, "potentialCostMinor": { "type": [ "number", "null" ] }, "baseConversions": { "type": [ "number", "null" ] }, "potentialConversions": { "type": [ "number", "null" ] } } } } }, "GoogleOptimizationScore": { "type": "object", "properties": { "score": { "type": [ "number", "null" ] }, "weight": { "type": [ "number", "null" ] }, "campaigns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "score": { "type": [ "number", "null" ] } } } } } }, "GoogleLocalServicesLead": { "type": "object", "properties": { "id": { "type": "string" }, "category": { "type": [ "string", "null" ] }, "service": { "type": [ "string", "null" ] }, "contactName": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] } } }, "GoogleConversionAction": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string" }, "type": { "type": "string" }, "countingType": { "type": [ "string", "null" ] }, "valueMinor": { "type": [ "integer", "null" ] }, "targetingFacets": { "type": "array", "items": { "type": "string" }, "description": "What `GET /v1/ads/targeting/search` accepts on this network, in picker order" }, "trackingMacros": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string" }, "description": { "type": "string" } } }, "description": "Macros the network expands inside a creative's tracking parameters" } } }, "AdSource": { "type": "object", "properties": { "connectionId": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "description": "Ad network id, e.g. `meta`" }, "name": { "type": "string" }, "workspaceId": { "type": "string", "format": "uuid" }, "adAccounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "`act_…`" }, "name": { "type": "string" }, "currency": { "type": "string" }, "status": { "type": "integer", "description": "Meta's account status code; 1 is active" } } } }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "instagramUserId": { "type": [ "string", "null" ] } } } }, "error": { "type": [ "string", "null" ], "description": "Set when Meta refused the listing, usually a revoked grant" } } }, "BoostablePost": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "text": { "type": "string" }, "thumbnailUrl": { "type": [ "string", "null" ] }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" }, "externalUrl": { "type": [ "string", "null" ] }, "postedAt": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "ExternalAd": { "type": "object", "properties": { "id": { "type": "string", "description": "Meta's ad id" }, "name": { "type": "string" }, "effectiveStatus": { "type": [ "string", "null" ] }, "campaignId": { "type": [ "string", "null" ] }, "campaignName": { "type": [ "string", "null" ] }, "objective": { "type": [ "string", "null" ] }, "budgetMinor": { "type": [ "integer", "null" ] }, "budgetType": { "type": [ "string", "null" ], "enum": [ "daily", "lifetime", null ] }, "endAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "connectionId": { "type": "string", "format": "uuid" }, "adAccountId": { "type": "string" }, "currency": { "type": [ "string", "null" ] }, "workspaceId": { "type": "string", "format": "uuid" } } }, "Audience": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "subtype": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "sizeLower": { "type": [ "integer", "null" ] }, "sizeUpper": { "type": [ "integer", "null" ] }, "deliveryStatus": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] } } }, "AudiencesResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "audiences": { "type": "array", "items": { "$ref": "#/components/schemas/Audience" } }, "pixels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } }, "workspaceId": { "type": "string", "format": "uuid" } } } }, "required": [ "data" ] }, "TargetingOption": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "detail": { "type": [ "string", "null" ] } } }, "AdBusinessCenter": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": [ "string", "null" ] } } }, "AdIdentity": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "avatarUrl": { "type": [ "string", "null" ] } } }, "SparkPost": { "type": "object", "properties": { "id": { "type": "string" }, "identityId": { "type": "string" }, "caption": { "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "views": { "type": "integer", "nullable": true } } }, "AdComment": { "type": "object", "properties": { "id": { "type": "string" }, "adId": { "type": [ "string", "null" ] }, "text": { "type": "string" }, "authorName": { "type": [ "string", "null" ] }, "authorAvatarUrl": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "likes": { "type": "integer" }, "replyCount": { "type": "integer" }, "hidden": { "type": "boolean" }, "parentId": { "type": [ "string", "null" ] } } }, "AdCommentsResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "comments": { "type": "array", "items": { "$ref": "#/components/schemas/AdComment" } }, "nextCursor": { "type": [ "string", "null" ] } } } }, "required": [ "data" ] }, "LeadForm": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "leadsCount": { "type": "integer" }, "createdAt": { "type": [ "string", "null" ] }, "questions": { "type": "array", "items": { "type": "string" } } } }, "LeadFormSource": { "type": "object", "properties": { "connectionId": { "type": "string", "format": "uuid" }, "connectionName": { "type": "string" }, "pageId": { "type": [ "string", "null" ] }, "pageName": { "type": [ "string", "null" ] }, "forms": { "type": "array", "items": { "$ref": "#/components/schemas/LeadForm" } }, "error": { "type": [ "string", "null" ] }, "workspaceId": { "type": "string", "format": "uuid" } } }, "Lead": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": [ "string", "null" ] }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } } } } }, "adName": { "type": [ "string", "null" ] }, "campaignName": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "isOrganic": { "type": "boolean" } } }, "LeadsResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "leads": { "type": "array", "items": { "$ref": "#/components/schemas/Lead" } }, "nextCursor": { "type": [ "string", "null" ] } } } }, "required": [ "data" ] }, "AdCampaign": { "type": "object", "properties": { "id": { "type": "string", "description": "Meta's campaign id" }, "name": { "type": "string" }, "status": { "type": "string", "description": "`ACTIVE`, `PAUSED`, `DELETED` or `ARCHIVED`" }, "effectiveStatus": { "type": [ "string", "null" ] }, "objective": { "type": [ "string", "null" ] }, "budgetMinor": { "type": [ "integer", "null" ], "description": "Null when the budget lives on the ad sets" }, "budgetType": { "type": [ "string", "null" ], "enum": [ "daily", "lifetime", null ] }, "createdAt": { "type": [ "string", "null" ] } } }, "AdSet": { "type": "object", "properties": { "id": { "type": "string", "description": "Meta's ad set id" }, "name": { "type": "string" }, "campaignId": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "effectiveStatus": { "type": [ "string", "null" ] }, "budgetMinor": { "type": [ "integer", "null" ] }, "budgetType": { "type": [ "string", "null" ], "enum": [ "daily", "lifetime", null ] }, "endAt": { "type": [ "string", "null" ] }, "optimizationGoal": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] } } }, "NetworkAd": { "type": "object", "properties": { "id": { "type": "string", "description": "Meta's ad id" }, "name": { "type": "string" }, "campaignId": { "type": [ "string", "null" ] }, "adSetId": { "type": [ "string", "null" ] }, "creativeId": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "effectiveStatus": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] } } }, "AdAccountTree": { "type": "object", "properties": { "adAccountId": { "type": "string" }, "currency": { "type": "string" }, "workspaceId": { "type": "string", "format": "uuid" }, "campaigns": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/AdCampaign" }, { "type": "object", "properties": { "adSets": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/AdSet" }, { "type": "object", "properties": { "ads": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkAd" } } } } ] } } } } ] } } } }, "AdCatalog": { "type": "object", "properties": { "id": { "type": "string", "description": "Meta's catalog id" }, "name": { "type": "string" }, "vertical": { "type": [ "string", "null" ] }, "productCount": { "type": [ "integer", "null" ] } } }, "AdCatalogsResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "catalogs": { "type": "array", "items": { "$ref": "#/components/schemas/AdCatalog" } }, "businesses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "description": "Business portfolios a new catalog can be created under" }, "workspaceId": { "type": "string", "format": "uuid" } } } }, "required": [ "data" ] }, "CatalogProduct": { "type": "object", "properties": { "id": { "type": "string" }, "retailerId": { "type": "string", "description": "Your own key for the product" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "availability": { "type": [ "string", "null" ] }, "condition": { "type": [ "string", "null" ] }, "priceMinor": { "type": [ "integer", "null" ], "description": "Minor units of `currency`" }, "currency": { "type": [ "string", "null" ] }, "imageUrl": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } } }, "CatalogProductsResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogProduct" } }, "nextCursor": { "type": [ "string", "null" ] } } } }, "required": [ "data" ] }, "CatalogBatchResult": { "type": "object", "properties": { "handles": { "type": "array", "items": { "type": "string" }, "description": "Meta's handles for the batch" }, "accepted": { "type": "integer", "description": "Products sent in this batch" } } }, "ProductFeed": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": [ "string", "null" ], "description": "Set when Meta fetches the file on a schedule" }, "schedule": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] } } }, "ProductFeedUpload": { "type": "object", "properties": { "id": { "type": "string" }, "startedAt": { "type": [ "string", "null" ] }, "endedAt": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "errorCount": { "type": [ "integer", "null" ] }, "warningCount": { "type": [ "integer", "null" ] } } }, "ProductSet": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "productCount": { "type": [ "integer", "null" ] }, "filter": { "type": [ "object", "null" ], "additionalProperties": true } } }, "ReachFrequencyPrediction": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "reach": { "type": [ "integer", "null" ] }, "impressions": { "type": [ "integer", "null" ] }, "frequencyCap": { "type": [ "integer", "null" ] }, "budgetMinor": { "type": [ "integer", "null" ], "description": "Account currency, minor units" }, "startAt": { "type": [ "string", "null" ] }, "endAt": { "type": [ "string", "null" ] }, "reserved": { "type": "boolean", "description": "True once the prediction holds inventory" } } }, "ReachFrequencyResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "predictions": { "type": "array", "items": { "$ref": "#/components/schemas/ReachFrequencyPrediction" } }, "workspaceId": { "type": "string", "format": "uuid" } } } }, "required": [ "data" ] }, "AdLibraryEntry": { "type": "object", "properties": { "id": { "type": "string" }, "pageId": { "type": [ "string", "null" ] }, "pageName": { "type": [ "string", "null" ] }, "bodies": { "type": "array", "items": { "type": "string" } }, "titles": { "type": "array", "items": { "type": "string" } }, "linkUrls": { "type": "array", "items": { "type": "string" } }, "snapshotUrl": { "type": [ "string", "null" ] }, "publisherPlatforms": { "type": "array", "items": { "type": "string" } }, "startedAt": { "type": [ "string", "null" ] }, "endedAt": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ], "description": "Only on the archive's disclosure entries" }, "spendLower": { "type": [ "integer", "null" ] }, "spendUpper": { "type": [ "integer", "null" ] }, "impressionsLower": { "type": [ "integer", "null" ] }, "impressionsUpper": { "type": [ "integer", "null" ] } } }, "AdLibraryResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/AdLibraryEntry" } }, "nextCursor": { "type": [ "string", "null" ] } } } }, "required": [ "data" ] }, "PartnershipCreator": { "type": "object", "properties": { "id": { "type": "string" }, "username": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "type": "string" } } } }, "AdActivity": { "type": "object", "properties": { "id": { "type": "string" }, "eventType": { "type": [ "string", "null" ] }, "actorName": { "type": [ "string", "null" ] }, "objectName": { "type": [ "string", "null" ] }, "objectType": { "type": [ "string", "null" ] }, "extraData": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] } } }, "AdActivityResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "activity": { "type": "array", "items": { "$ref": "#/components/schemas/AdActivity" } }, "workspaceId": { "type": "string", "format": "uuid" } } } }, "required": [ "data" ] }, "AdLabel": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": [ "string", "null" ] } } }, "AdStudy": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "startAt": { "type": [ "string", "null" ] }, "endAt": { "type": [ "string", "null" ] } } }, "IosCampaignLimits": { "type": "object", "properties": { "limit": { "type": [ "integer", "null" ] }, "used": { "type": [ "integer", "null" ] }, "appId": { "type": [ "string", "null" ] } } }, "HighDemandPeriod": { "type": "object", "properties": { "id": { "type": "string" }, "startAt": { "type": [ "string", "null" ] }, "endAt": { "type": [ "string", "null" ] }, "budgetValue": { "type": [ "number", "null" ] }, "budgetValueType": { "type": [ "string", "null" ] } } }, "ValueRuleSet": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": [ "string", "null" ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "condition": { "type": [ "string", "null" ] }, "multiplier": { "type": [ "number", "null" ] } } } } } }, "BidPricing": { "type": "object", "properties": { "currency": { "type": "string" }, "suggestedBidMinor": { "type": [ "integer", "null" ] }, "minBidMinor": { "type": [ "integer", "null" ] }, "maxBidMinor": { "type": [ "integer", "null" ] }, "dailyBudgetFloorMinor": { "type": [ "integer", "null" ] } } }, "SupplyForecast": { "type": "object", "properties": { "currency": { "type": "string" }, "impressions": { "type": [ "integer", "null" ] }, "clicks": { "type": [ "integer", "null" ] }, "spendMinor": { "type": [ "integer", "null" ] }, "windowDays": { "type": [ "integer", "null" ], "description": "Days the forecast covers" }, "ready": { "type": "boolean", "description": "False while the network has no answer for that audience" } } }, "ConversionRule": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "purchase", "lead", "sign_up", "add_to_cart", "download", "install", "key_page_view", "other" ] }, "attribution": { "type": "string", "enum": [ "last_touch", "each_campaign" ] }, "postClickWindowDays": { "type": "integer" }, "viewThroughWindowDays": { "type": "integer" }, "valueMinor": { "type": [ "integer", "null" ] }, "currency": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "createdAt": { "type": [ "string", "null" ] }, "campaignIds": { "type": "array", "items": { "type": "string" }, "description": "Ad sets this rule is attached to" } } }, "ConversionMetrics": { "type": "object", "properties": { "conversions": { "type": "integer" }, "postClickConversions": { "type": "integer" }, "viewThroughConversions": { "type": "integer" }, "valueMinor": { "type": "integer" }, "costPerConversionMinor": { "type": [ "integer", "null" ] } } }, "AdCreative": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "format": { "type": "string", "enum": [ "image", "video", "carousel", "post", "other" ] }, "status": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "link": { "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "callToAction": { "type": [ "string", "null" ] }, "urlTags": { "type": [ "string", "null" ] } } }, "BulkAdStatusResult": { "type": "object", "properties": { "id": { "type": "string" }, "level": { "type": "string", "enum": [ "campaign", "ad_set", "ad" ] }, "ok": { "type": "boolean" }, "error": { "type": [ "string", "null" ] } } }, "InsightsMetrics": { "type": "object", "properties": { "impressions": { "type": "integer" }, "reach": { "type": "integer" }, "clicks": { "type": "integer" }, "spendMinor": { "type": "integer", "description": "Account currency, minor units" }, "ctr": { "type": "number", "description": "Clicks per impression, as a percentage" }, "leads": { "type": "integer" } } }, "AdInsightsReport": { "type": "object", "properties": { "objectId": { "type": "string" }, "currency": { "type": [ "string", "null" ] }, "since": { "type": "string" }, "until": { "type": "string" }, "breakdownBy": { "type": [ "string", "null" ], "enum": [ "age", "gender", "placement", "country", null ] }, "totals": { "oneOf": [ { "$ref": "#/components/schemas/InsightsMetrics" }, { "type": "null" } ] }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "metrics": { "$ref": "#/components/schemas/InsightsMetrics" } } } }, "timeline": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "metrics": { "$ref": "#/components/schemas/InsightsMetrics" } } } } } }, "ReachEstimate": { "type": "object", "properties": { "lower": { "type": [ "integer", "null" ] }, "upper": { "type": [ "integer", "null" ] }, "ready": { "type": "boolean" } } }, "LeadFormDetail": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "leadsCount": { "type": "integer" }, "createdAt": { "type": [ "string", "null" ] }, "questions": { "type": "array", "items": { "type": "string" } }, "pageId": { "type": [ "string", "null" ] }, "privacyPolicyUrl": { "type": [ "string", "null" ] }, "locale": { "type": [ "string", "null" ] } } }, "FeedLead": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "leadId": { "type": "string", "description": "Meta's lead id" }, "connectionId": { "type": "string", "format": "uuid" }, "pageId": { "type": "string" }, "formId": { "type": [ "string", "null" ] }, "adId": { "type": [ "string", "null" ] }, "adName": { "type": [ "string", "null" ] }, "campaignName": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "isOrganic": { "type": "boolean" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } } } } }, "submittedAt": { "type": "string", "format": "date-time" }, "workspaceId": { "type": "string", "format": "uuid" } } }, "LeadPage": { "type": "object", "properties": { "connectionId": { "type": "string", "format": "uuid" }, "pageId": { "type": "string" }, "pageName": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "workspaceId": { "type": "string", "format": "uuid" } } }, "MediaLibraryItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri", "description": "The asset's identity; store this on a post" }, "visibility": { "type": "string", "enum": [ "private", "public" ] }, "type": { "type": "string", "enum": [ "image", "video", "gif", "document" ] }, "mime_type": { "type": "string" }, "size": { "type": "integer", "description": "File size in bytes" }, "alt_text": { "type": [ "string", "null" ] }, "alt_text_source": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "folder_id": { "type": [ "string", "null" ], "format": "uuid" }, "origin": { "type": [ "string", "null" ] }, "source_url": { "type": [ "string", "null" ] }, "synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "brand_role": { "type": [ "string", "null" ], "enum": [ "logo", "product", "person", "background", null ] }, "brand_voice_id": { "type": [ "string", "null" ], "format": "uuid" }, "generation_run_id": { "type": [ "string", "null" ] }, "has_person_consent": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "preview_url": { "type": "string", "description": "Permanent, membership-checked read URL" }, "share": { "type": [ "object", "null" ], "description": "The live share link; present only with `shared=true`", "properties": { "url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "created_by_name": { "type": [ "string", "null" ] }, "source": { "type": "string" } } } }, "required": [ "id", "workspace_id", "name", "url", "type", "size", "created_at", "preview_url" ] }, "UploadedMedia": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Media library id (present when `workspaceId` was provided)" }, "type": { "type": "string", "enum": [ "image", "video", "gif", "document" ] }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "preview_url": { "type": "string", "format": "uri", "description": "Permanent, membership-checked read URL" }, "size": { "type": "integer" } }, "required": [ "type", "name", "url", "size" ] }, "UploadLimits": { "type": "object", "properties": { "max_file_bytes": { "type": "integer", "description": "The largest file this account may upload, by any route. Grows with the connected-account count (100 MB up to 2 accounts, 400 MB up to 7, 2 GB up to 15, 5 GB beyond) and is 5 GB with the Large Uploads add-on." }, "source": { "type": "string", "enum": [ "accounts", "add_on", "bypass" ], "description": "What set the ceiling" }, "connected_accounts": { "type": "integer" }, "large_uploads_enabled": { "type": "boolean" }, "next_tier": { "type": [ "object", "null" ], "properties": { "up_to_accounts": { "type": [ "integer", "null" ] }, "max_file_bytes": { "type": "integer" } }, "description": "The next ceiling up and the account count that unlocks it; null at the top" }, "multipart_max_file_bytes": { "type": "integer", "description": "What a multipart request (`/v1/media/upload`, or a post with files) can carry per file. Larger files go through direct upload." }, "max_files_per_upload": { "type": "integer" }, "direct_upload_available": { "type": "boolean" }, "allowed_types": { "type": "array", "items": { "type": "string" } } }, "required": [ "max_file_bytes", "source", "connected_accounts", "large_uploads_enabled", "multipart_max_file_bytes", "max_files_per_upload", "direct_upload_available", "allowed_types" ] }, "PresignedUpload": { "type": "object", "properties": { "upload_id": { "type": "string", "format": "uuid", "description": "Pass to the complete step" }, "upload_url": { "type": "string", "format": "uri", "description": "PUT the raw bytes here" }, "method": { "type": "string", "enum": [ "PUT" ] }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Headers the PUT must carry exactly (Content-Type)" }, "expires_at": { "type": "string", "format": "date-time", "description": "When the signed URL stops accepting the PUT" }, "max_file_bytes": { "type": "integer", "description": "The account ceiling the file was checked against" } }, "required": [ "upload_id", "upload_url", "method", "headers", "expires_at", "max_file_bytes" ] } }, "responses": { "Unauthorized": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "Forbidden": { "description": "The API key lacks the required scope, or a mutating route was called without an active subscription (`subscription_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "NotFound": { "description": "Resource not found or not accessible to the authenticated user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "ValidationError": { "description": "Request body or parameters failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "InvalidId": { "description": "Malformed id path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "Conflict": { "description": "The request conflicts with the current state of the resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "PaymentRequired": { "description": "The AI balance cannot cover the run. The body carries `upgrade_url`, where funds can be added.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "ServiceUnavailable": { "description": "The feature is not set up on this deployment (`not_configured`) or its provider is unavailable (`service_unavailable`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "RateLimited": { "description": "Too many requests for this API key in the current minute. The body carries `retry_after` (seconds) and the response carries `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } } }, "headers": { "XRequestId": { "description": "Unique id of this request; quote it to support", "schema": { "type": "string" } } } } }