{ "openapi": "3.1.0", "info": { "title": "AllProfiles Organization API", "version": "1.0.0", "description": "Organization-bound automation for listing profiles, managing rentals and replying to existing customer conversations. The token's issuing actor keeps the same service permissions as the UI. All write calls require Idempotency-Key; unsupported admin/customer/personal-wallet actions are excluded. Financial write scopes (rentals:write, payouts:write, payouts:withdraw, payroll:write, payroll:pay) require separate financial API enablement and default to unavailable. Read /developer/capabilities for the currently enabled actions and scopes." }, "servers": [ { "url": "https://allprofiles-be.onrender.com/api/v1/org", "description": "Documented backend origin; verify deployment and API enablement before use." }, { "url": "http://localhost:4000/api/v1/org", "description": "Local API; override when your development port differs." } ], "tags": [ { "name": "Profiles" }, { "name": "Rentals" }, { "name": "Clients" }, { "name": "Hosted agents" }, { "name": "Rule templates" }, { "name": "Organization" }, { "name": "Team" }, { "name": "Chat templates" }, { "name": "Discounts" }, { "name": "Analytics" }, { "name": "Chat" }, { "name": "Chat attachments" }, { "name": "Rental invoices" }, { "name": "Payout connections" }, { "name": "Payroll" }, { "name": "Stripe Connect" }, { "name": "Webhooks" }, { "name": "Events" }, { "name": "Developer tools" } ], "paths": { "/agent-profiles": { "get": { "operationId": "listProfiles", "tags": [ "Profiles" ], "summary": "List organization profiles", "description": "Default 50, maximum 100. Follow nextCursor with the same search, tenant and resource until null. Creation cutoff excludes later inserts; mutable fields may change between pages. Unsupported search returns 400.\n\nActor capability: member. Required token scopes: profiles:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "See list organization profiles pagination and response notes.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "See list organization profiles pagination and response notes.", "schema": { "type": "string", "minLength": 1, "maxLength": 768 } }, { "name": "search", "in": "query", "required": false, "description": "See list organization profiles pagination and response notes.", "schema": { "type": "string", "minLength": 0, "maxLength": 200 } } ], "responses": { "200": { "description": "{data: bounded profiles summaries[], nextCursor: string | null}. Fetch detail endpoints for full records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "createdById": { "type": "string", "format": "uuid" }, "operatingAgentId": { "type": [ "string", "null" ], "format": "uuid" }, "platform": { "type": "string", "enum": [ "linkedin", "facebook", "x", "upwork", "reddit" ] }, "displayName": { "type": "string" }, "headline": { "type": [ "string", "null" ] }, "profileUrl": { "type": "string" }, "photoUrl": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "currentCompany": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "available", "rented", "unlisted" ] }, "priceInCents": { "type": "integer" }, "pricingPeriod": { "type": "string", "enum": [ "day", "week", "month" ] }, "payoutMethod": { "type": "string", "enum": [ "fiat", "crypto" ] }, "twoFactorKey": { "type": [ "string", "null" ] }, "antiDetectBrowser": { "type": [ "string", "null" ] }, "canBeRehosted": { "type": "boolean" }, "agentPayoutRateCents": { "type": [ "integer", "null" ] }, "monthlyExpenses": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "amountCents": { "type": "integer" } }, "required": [ "label", "amountCents" ], "additionalProperties": false } }, "connectionCount": { "type": [ "integer", "null" ] }, "isVerified": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "createdById", "operatingAgentId", "platform", "displayName", "headline", "profileUrl", "photoUrl", "city", "currentCompany", "status", "priceInCents", "pricingPeriod", "payoutMethod", "antiDetectBrowser", "canBeRehosted", "agentPayoutRateCents", "monthlyExpenses", "connectionCount", "isVerified", "createdAt", "updatedAt" ], "additionalProperties": false }, "maxItems": 100, "minItems": 0 }, "nextCursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 768 } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "profiles:read" ], "x-actor-capability": "member", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false }, "post": { "operationId": "createProfile", "tags": [ "Profiles" ], "summary": "Save a profile", "description": "antiDetectBrowser=none keeps the profile unlisted. Upwork imports require a reviewed import receipt; listing affects the public marketplace.\n\nActor capability: manager. Required token scopes: profiles:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Created profile. Review unlisted draft, then PATCH status=available to publish.", "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "linkedin", "facebook", "x", "upwork", "reddit" ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 200 }, "headline": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "profileUrl": { "type": "string", "format": "uri", "maxLength": 2048 }, "photoUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 2048 }, "bannerUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 2048 }, "city": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "currentCompany": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "antiDetectBrowser": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "canBeRehosted": { "type": "boolean" }, "priceInCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "pricingPeriod": { "type": "string", "enum": [ "day", "week", "month" ] }, "description": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "connectionCount": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "gender": { "type": [ "string", "null" ], "enum": [ "male", "female", "other", null ] }, "isVerified": { "type": "boolean" }, "payoutMethod": { "type": "string", "enum": [ "fiat", "crypto" ] }, "scrapedData": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Platform scrape metadata. Keep credentials out of this field." }, "isAutoScraped": { "type": "boolean" }, "operatingAgentId": { "type": [ "string", "null" ], "format": "uuid" }, "agentPayoutRateCents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "monthlyExpenses": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 0, "maxLength": 60 }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "label", "amountCents" ], "additionalProperties": false }, "maxItems": 20, "minItems": 0 }, "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "createdById": { "type": "string", "format": "uuid" }, "publicSlug": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "twoFactorKey": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000, "description": "Omitted by default; requires profiles:credentials:read on a Profiles operation." }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "enum": [ "available", "rented", "unlisted" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "platform", "displayName", "profileUrl", "status", "priceInCents", "pricingPeriod" ], "additionalProperties": true } } } }, "201": { "description": "Created profile. Review unlisted draft, then PATCH status=available to publish.", "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "linkedin", "facebook", "x", "upwork", "reddit" ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 200 }, "headline": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "profileUrl": { "type": "string", "format": "uri", "maxLength": 2048 }, "photoUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 2048 }, "bannerUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 2048 }, "city": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "currentCompany": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "antiDetectBrowser": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "canBeRehosted": { "type": "boolean" }, "priceInCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "pricingPeriod": { "type": "string", "enum": [ "day", "week", "month" ] }, "description": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "connectionCount": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "gender": { "type": [ "string", "null" ], "enum": [ "male", "female", "other", null ] }, "isVerified": { "type": "boolean" }, "payoutMethod": { "type": "string", "enum": [ "fiat", "crypto" ] }, "scrapedData": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Platform scrape metadata. Keep credentials out of this field." }, "isAutoScraped": { "type": "boolean" }, "operatingAgentId": { "type": [ "string", "null" ], "format": "uuid" }, "agentPayoutRateCents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "monthlyExpenses": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 0, "maxLength": 60 }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "label", "amountCents" ], "additionalProperties": false }, "maxItems": 20, "minItems": 0 }, "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "createdById": { "type": "string", "format": "uuid" }, "publicSlug": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "twoFactorKey": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000, "description": "Omitted by default; requires profiles:credentials:read on a Profiles operation." }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "enum": [ "available", "rented", "unlisted" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "platform", "displayName", "profileUrl", "status", "priceInCents", "pricingPeriod" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "linkedin", "facebook", "x", "upwork", "reddit" ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 200 }, "headline": { "type": "string", "minLength": 0, "maxLength": 5000 }, "profileUrl": { "type": "string", "format": "uri", "maxLength": 2048 }, "photoUrl": { "type": "string", "minLength": 0, "maxLength": 2048 }, "bannerUrl": { "type": "string", "minLength": 0, "maxLength": 2048 }, "city": { "type": "string", "minLength": 0, "maxLength": 200 }, "currentCompany": { "type": "string", "minLength": 0, "maxLength": 200 }, "twoFactorKey": { "type": "string", "minLength": 0, "maxLength": 200, "description": "Sensitive credential input. Never returned in webhook payloads; keep bot keys narrowly scoped." }, "antiDetectBrowser": { "type": "string", "minLength": 1, "maxLength": 80 }, "canBeRehosted": { "type": "boolean" }, "priceInCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "pricingPeriod": { "type": "string", "enum": [ "day", "week", "month" ] }, "description": { "type": "string", "minLength": 0, "maxLength": 5000 }, "connectionCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "gender": { "type": "string", "enum": [ "male", "female", "other" ] }, "isVerified": { "type": "boolean" }, "payoutMethod": { "type": "string", "enum": [ "fiat", "crypto" ] }, "scrapedData": { "type": "object", "additionalProperties": true, "description": "Platform scrape metadata. Keep credentials out of this field." }, "upworkImportId": { "type": "string", "format": "uuid" }, "isAutoScraped": { "type": "boolean" }, "listImmediately": { "type": "boolean", "default": false, "description": "Automation saves a draft by default. Review before publishing with status=available." }, "operatingAgentId": { "type": "string", "format": "uuid" }, "agentPayoutRateCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "monthlyExpenses": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 0, "maxLength": 60 }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "label", "amountCents" ], "additionalProperties": false }, "maxItems": 20, "minItems": 0 } }, "required": [ "platform", "displayName", "profileUrl", "antiDetectBrowser", "priceInCents" ], "additionalProperties": false } } } }, "x-required-scopes": [ "profiles:write" ], "x-actor-capability": "manager", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/agent-profiles/{id}": { "get": { "operationId": "getProfile", "tags": [ "Profiles" ], "summary": "Read a profile", "description": "Actor capability: member. Required token scopes: profiles:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "One accessible organization profile; unknown or inaccessible profile returns 404.", "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "linkedin", "facebook", "x", "upwork", "reddit" ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 200 }, "headline": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "profileUrl": { "type": "string", "format": "uri", "maxLength": 2048 }, "photoUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 2048 }, "bannerUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 2048 }, "city": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "currentCompany": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "antiDetectBrowser": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "canBeRehosted": { "type": "boolean" }, "priceInCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "pricingPeriod": { "type": "string", "enum": [ "day", "week", "month" ] }, "description": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "connectionCount": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "gender": { "type": [ "string", "null" ], "enum": [ "male", "female", "other", null ] }, "isVerified": { "type": "boolean" }, "payoutMethod": { "type": "string", "enum": [ "fiat", "crypto" ] }, "scrapedData": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Platform scrape metadata. Keep credentials out of this field." }, "isAutoScraped": { "type": "boolean" }, "operatingAgentId": { "type": [ "string", "null" ], "format": "uuid" }, "agentPayoutRateCents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "monthlyExpenses": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 0, "maxLength": 60 }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "label", "amountCents" ], "additionalProperties": false }, "maxItems": 20, "minItems": 0 }, "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "createdById": { "type": "string", "format": "uuid" }, "publicSlug": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "twoFactorKey": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000, "description": "Omitted by default; requires profiles:credentials:read on a Profiles operation." }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "enum": [ "available", "rented", "unlisted" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "platform", "displayName", "profileUrl", "status", "priceInCents", "pricingPeriod" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "profiles:read" ], "x-actor-capability": "member", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false }, "patch": { "operationId": "updateProfile", "tags": [ "Profiles" ], "summary": "Edit or publish a profile", "description": "Actor capability: member. Required token scopes: profiles:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Updated profile. Existing member field restrictions, rental-state rules and duplicate URL checks apply.", "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "linkedin", "facebook", "x", "upwork", "reddit" ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 200 }, "headline": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "profileUrl": { "type": "string", "format": "uri", "maxLength": 2048 }, "photoUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 2048 }, "bannerUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 2048 }, "city": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "currentCompany": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "antiDetectBrowser": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "canBeRehosted": { "type": "boolean" }, "priceInCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "pricingPeriod": { "type": "string", "enum": [ "day", "week", "month" ] }, "description": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "connectionCount": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "gender": { "type": [ "string", "null" ], "enum": [ "male", "female", "other", null ] }, "isVerified": { "type": "boolean" }, "payoutMethod": { "type": "string", "enum": [ "fiat", "crypto" ] }, "scrapedData": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Platform scrape metadata. Keep credentials out of this field." }, "isAutoScraped": { "type": "boolean" }, "operatingAgentId": { "type": [ "string", "null" ], "format": "uuid" }, "agentPayoutRateCents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "monthlyExpenses": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 0, "maxLength": 60 }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "label", "amountCents" ], "additionalProperties": false }, "maxItems": 20, "minItems": 0 }, "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "createdById": { "type": "string", "format": "uuid" }, "publicSlug": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "twoFactorKey": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000, "description": "Omitted by default; requires profiles:credentials:read on a Profiles operation." }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "enum": [ "available", "rented", "unlisted" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "platform", "displayName", "profileUrl", "status", "priceInCents", "pricingPeriod" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "linkedin", "facebook", "x", "upwork", "reddit" ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 200 }, "headline": { "type": "string", "minLength": 0, "maxLength": 5000 }, "profileUrl": { "type": "string", "format": "uri", "maxLength": 2048 }, "photoUrl": { "type": "string", "minLength": 0, "maxLength": 2048 }, "bannerUrl": { "type": "string", "minLength": 0, "maxLength": 2048 }, "city": { "type": "string", "minLength": 0, "maxLength": 200 }, "currentCompany": { "type": "string", "minLength": 0, "maxLength": 200 }, "twoFactorKey": { "type": "string", "minLength": 0, "maxLength": 200, "description": "Sensitive credential input. Never returned in webhook payloads; keep bot keys narrowly scoped." }, "antiDetectBrowser": { "type": "string", "minLength": 1, "maxLength": 80 }, "canBeRehosted": { "type": "boolean" }, "priceInCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "pricingPeriod": { "type": "string", "enum": [ "day", "week", "month" ] }, "description": { "type": "string", "minLength": 0, "maxLength": 5000 }, "connectionCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "gender": { "type": "string", "enum": [ "male", "female", "other" ] }, "isVerified": { "type": "boolean" }, "payoutMethod": { "type": "string", "enum": [ "fiat", "crypto" ] }, "scrapedData": { "type": "object", "additionalProperties": true, "description": "Platform scrape metadata. Keep credentials out of this field." }, "upworkImportId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "available", "rented", "unlisted" ], "description": "available publishes; unlisted hides. rented is subject to service lifecycle checks; use rental actions for paid rentals." } }, "required": [], "additionalProperties": false } } } }, "x-required-scopes": [ "profiles:write" ], "x-actor-capability": "member", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true }, "delete": { "operationId": "deleteProfile", "tags": [ "Profiles" ], "summary": "Delete a profile", "description": "Actor capability: manager. Required token scopes: profiles:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "{deleted:true}. Active rentals must be ended through their lifecycle before deletion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "profiles:write" ], "x-actor-capability": "manager", "x-risk": "destructive", "x-human-required": false, "x-idempotency-required": true } }, "/agent-profiles/imports": { "post": { "operationId": "startProfileImport", "tags": [ "Profiles" ], "summary": "Import a profile", "description": "Use one endpoint for LinkedIn and Upwork. The Idempotency-Key supplies durable action identity; no separate requestId is needed. Repeating the same write returns its original response: GET statusUrl for current state. Existing organization permissions, duplicate checks and provider quotas apply. Imports can incur provider costs. This never creates or publishes a profile. Upwork results expire after 24 hours; its job reference is retained for 30 days. An uncertain start must not be retried with a new key.\n\nActor capability: manager. Required token scopes: profiles:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Import reference with type, status and statusUrl. LinkedIn completes synchronously; Upwork returns a pending job. Review profile before saving a listing. For Upwork, pass upworkImportId to profile creation after review.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "statusUrl": { "type": "string", "minLength": 0, "maxLength": 2048 }, "type": { "type": "string", "enum": [ "linkedin" ] }, "status": { "type": "string", "enum": [ "ready" ] }, "profile": { "type": "object", "properties": { "firstName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "lastName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "displayName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "headline": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "about": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "photoUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "bannerUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "city": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "currentCompany": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "followers": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "connections": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "gender": { "type": "null" }, "isVerified": { "type": [ "boolean", "null" ] }, "verifications": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "description": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "verifiedAt": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "type", "description", "verifiedAt" ], "additionalProperties": true } }, "firstRoleYear": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "totalExperienceYears": { "type": [ "number", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "experiences": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "companyName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "companyLogoUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "companyLinkedinUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "employmentType": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "startDate": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "endDate": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "duration": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "location": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "workMode": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "description": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "title", "companyName", "companyLogoUrl", "companyLinkedinUrl", "employmentType", "startDate", "endDate", "duration", "location", "workMode", "description" ], "additionalProperties": true } } }, "required": [ "displayName", "headline", "about", "photoUrl", "bannerUrl", "city", "currentCompany", "followers", "connections", "gender", "isVerified", "verifications", "firstRoleYear", "totalExperienceYears", "experiences" ], "additionalProperties": true }, "fetchedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "statusUrl", "type", "status", "profile", "fetchedAt" ], "additionalProperties": true }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "statusUrl": { "type": "string", "minLength": 0, "maxLength": 2048 }, "type": { "type": "string", "enum": [ "linkedin" ] }, "status": { "type": "string", "enum": [ "failed" ] }, "message": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "id", "statusUrl", "type", "status", "message" ], "additionalProperties": true }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "statusUrl": { "type": "string", "minLength": 0, "maxLength": 2048 }, "type": { "type": "string", "enum": [ "upwork" ] }, "status": { "type": "string", "enum": [ "pending" ] }, "upworkImportId": { "type": "string", "format": "uuid" } }, "required": [ "id", "statusUrl", "type", "status", "upworkImportId" ], "additionalProperties": true }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "statusUrl": { "type": "string", "minLength": 0, "maxLength": 2048 }, "type": { "type": "string", "enum": [ "upwork" ] }, "status": { "type": "string", "enum": [ "ready" ] }, "upworkImportId": { "type": "string", "format": "uuid" }, "profile": { "type": "object", "properties": { "profileUrl": { "type": "string", "minLength": 0, "maxLength": 5000 }, "displayName": { "type": "string", "minLength": 0, "maxLength": 5000 }, "headline": { "type": "string", "minLength": 0, "maxLength": 5000 }, "description": { "type": "string", "minLength": 0, "maxLength": 5000 }, "city": { "type": "string", "minLength": 0, "maxLength": 5000 }, "upwork": { "type": "object", "properties": { "jobSuccessScore": { "type": "integer", "minimum": 0, "maximum": 100 }, "completedJobs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalHours": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "totalEarningsUsd": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "hourlyRateUsd": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "talentBadge": { "type": "string", "enum": [ "rising-talent", "top-rated", "top-rated-plus", "expert-vetted" ] }, "skills": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "source": { "type": "string", "enum": [ "manual", "reviewed-import" ] }, "provider": { "type": "string", "enum": [ "moxlade" ] }, "fetchedAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "source", "updatedAt" ], "additionalProperties": true } }, "required": [ "profileUrl", "displayName", "headline", "description", "city", "upwork" ], "additionalProperties": true }, "fetchedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "statusUrl", "type", "status", "upworkImportId", "profile", "fetchedAt" ], "additionalProperties": true }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "statusUrl": { "type": "string", "minLength": 0, "maxLength": 2048 }, "type": { "type": "string", "enum": [ "upwork" ] }, "status": { "type": "string", "enum": [ "failed" ] }, "upworkImportId": { "type": "string", "format": "uuid" }, "message": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "id", "statusUrl", "type", "status", "upworkImportId", "message" ], "additionalProperties": true } ] } } } }, "201": { "description": "Import reference with type, status and statusUrl. LinkedIn completes synchronously; Upwork returns a pending job. Review profile before saving a listing. For Upwork, pass upworkImportId to profile creation after review.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "statusUrl": { "type": "string", "minLength": 0, "maxLength": 2048 }, "type": { "type": "string", "enum": [ "linkedin" ] }, "status": { "type": "string", "enum": [ "ready" ] }, "profile": { "type": "object", "properties": { "firstName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "lastName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "displayName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "headline": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "about": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "photoUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "bannerUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "city": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "currentCompany": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "followers": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "connections": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "gender": { "type": "null" }, "isVerified": { "type": [ "boolean", "null" ] }, "verifications": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "description": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "verifiedAt": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "type", "description", "verifiedAt" ], "additionalProperties": true } }, "firstRoleYear": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "totalExperienceYears": { "type": [ "number", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "experiences": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "companyName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "companyLogoUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "companyLinkedinUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "employmentType": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "startDate": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "endDate": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "duration": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "location": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "workMode": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "description": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "title", "companyName", "companyLogoUrl", "companyLinkedinUrl", "employmentType", "startDate", "endDate", "duration", "location", "workMode", "description" ], "additionalProperties": true } } }, "required": [ "displayName", "headline", "about", "photoUrl", "bannerUrl", "city", "currentCompany", "followers", "connections", "gender", "isVerified", "verifications", "firstRoleYear", "totalExperienceYears", "experiences" ], "additionalProperties": true }, "fetchedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "statusUrl", "type", "status", "profile", "fetchedAt" ], "additionalProperties": true }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "statusUrl": { "type": "string", "minLength": 0, "maxLength": 2048 }, "type": { "type": "string", "enum": [ "linkedin" ] }, "status": { "type": "string", "enum": [ "failed" ] }, "message": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "id", "statusUrl", "type", "status", "message" ], "additionalProperties": true }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "statusUrl": { "type": "string", "minLength": 0, "maxLength": 2048 }, "type": { "type": "string", "enum": [ "upwork" ] }, "status": { "type": "string", "enum": [ "pending" ] }, "upworkImportId": { "type": "string", "format": "uuid" } }, "required": [ "id", "statusUrl", "type", "status", "upworkImportId" ], "additionalProperties": true }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "statusUrl": { "type": "string", "minLength": 0, "maxLength": 2048 }, "type": { "type": "string", "enum": [ "upwork" ] }, "status": { "type": "string", "enum": [ "ready" ] }, "upworkImportId": { "type": "string", "format": "uuid" }, "profile": { "type": "object", "properties": { "profileUrl": { "type": "string", "minLength": 0, "maxLength": 5000 }, "displayName": { "type": "string", "minLength": 0, "maxLength": 5000 }, "headline": { "type": "string", "minLength": 0, "maxLength": 5000 }, "description": { "type": "string", "minLength": 0, "maxLength": 5000 }, "city": { "type": "string", "minLength": 0, "maxLength": 5000 }, "upwork": { "type": "object", "properties": { "jobSuccessScore": { "type": "integer", "minimum": 0, "maximum": 100 }, "completedJobs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalHours": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "totalEarningsUsd": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "hourlyRateUsd": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "talentBadge": { "type": "string", "enum": [ "rising-talent", "top-rated", "top-rated-plus", "expert-vetted" ] }, "skills": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "source": { "type": "string", "enum": [ "manual", "reviewed-import" ] }, "provider": { "type": "string", "enum": [ "moxlade" ] }, "fetchedAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "source", "updatedAt" ], "additionalProperties": true } }, "required": [ "profileUrl", "displayName", "headline", "description", "city", "upwork" ], "additionalProperties": true }, "fetchedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "statusUrl", "type", "status", "upworkImportId", "profile", "fetchedAt" ], "additionalProperties": true }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "statusUrl": { "type": "string", "minLength": 0, "maxLength": 2048 }, "type": { "type": "string", "enum": [ "upwork" ] }, "status": { "type": "string", "enum": [ "failed" ] }, "upworkImportId": { "type": "string", "format": "uuid" }, "message": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "id", "statusUrl", "type", "status", "upworkImportId", "message" ], "additionalProperties": true } ] } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "linkedin", "upwork" ], "description": "Platform to import. More platforms can be added without changing this endpoint." }, "url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "HTTPS public profile URL: LinkedIn /in/ or Upwork /freelancers/~… matching type." }, "excludeProfileId": { "type": "string", "format": "uuid", "description": "Optional profile in this organization to exclude from duplicate checks when refreshing its details." } }, "required": [ "type", "url" ], "additionalProperties": false } } } }, "x-required-scopes": [ "profiles:write" ], "x-actor-capability": "manager", "x-risk": "external", "x-human-required": false, "x-idempotency-required": true } }, "/agent-profiles/imports/{id}": { "get": { "operationId": "getProfileImport", "tags": [ "Profiles" ], "summary": "Read an import", "description": "Read the id returned by POST /agent-profiles/imports, not an Upwork provider job ID. Poll pending jobs with backoff; the existing provider poll lease prevents duplicate provider reads. LinkedIn results come from the encrypted action receipt. Upwork results expire after 24 hours and job references after 30 days; expired results cannot be applied. A still-running or uncertain initial request returns 409 rather than starting another paid import. Legacy import IDs must use their legacy status route.\n\nActor capability: manager. Required token scopes: profiles:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The same import envelope with the latest pending, ready or failed status. Reference IDs are bound to the issuing actor and organization.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "statusUrl": { "type": "string", "minLength": 0, "maxLength": 2048 }, "type": { "type": "string", "enum": [ "linkedin" ] }, "status": { "type": "string", "enum": [ "ready" ] }, "profile": { "type": "object", "properties": { "firstName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "lastName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "displayName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "headline": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "about": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "photoUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "bannerUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "city": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "currentCompany": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "followers": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "connections": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "gender": { "type": "null" }, "isVerified": { "type": [ "boolean", "null" ] }, "verifications": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "description": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "verifiedAt": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "type", "description", "verifiedAt" ], "additionalProperties": true } }, "firstRoleYear": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "totalExperienceYears": { "type": [ "number", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "experiences": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "companyName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "companyLogoUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "companyLinkedinUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "employmentType": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "startDate": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "endDate": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "duration": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "location": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "workMode": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "description": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "title", "companyName", "companyLogoUrl", "companyLinkedinUrl", "employmentType", "startDate", "endDate", "duration", "location", "workMode", "description" ], "additionalProperties": true } } }, "required": [ "displayName", "headline", "about", "photoUrl", "bannerUrl", "city", "currentCompany", "followers", "connections", "gender", "isVerified", "verifications", "firstRoleYear", "totalExperienceYears", "experiences" ], "additionalProperties": true }, "fetchedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "statusUrl", "type", "status", "profile", "fetchedAt" ], "additionalProperties": true }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "statusUrl": { "type": "string", "minLength": 0, "maxLength": 2048 }, "type": { "type": "string", "enum": [ "linkedin" ] }, "status": { "type": "string", "enum": [ "failed" ] }, "message": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "id", "statusUrl", "type", "status", "message" ], "additionalProperties": true }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "statusUrl": { "type": "string", "minLength": 0, "maxLength": 2048 }, "type": { "type": "string", "enum": [ "upwork" ] }, "status": { "type": "string", "enum": [ "pending" ] }, "upworkImportId": { "type": "string", "format": "uuid" } }, "required": [ "id", "statusUrl", "type", "status", "upworkImportId" ], "additionalProperties": true }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "statusUrl": { "type": "string", "minLength": 0, "maxLength": 2048 }, "type": { "type": "string", "enum": [ "upwork" ] }, "status": { "type": "string", "enum": [ "ready" ] }, "upworkImportId": { "type": "string", "format": "uuid" }, "profile": { "type": "object", "properties": { "profileUrl": { "type": "string", "minLength": 0, "maxLength": 5000 }, "displayName": { "type": "string", "minLength": 0, "maxLength": 5000 }, "headline": { "type": "string", "minLength": 0, "maxLength": 5000 }, "description": { "type": "string", "minLength": 0, "maxLength": 5000 }, "city": { "type": "string", "minLength": 0, "maxLength": 5000 }, "upwork": { "type": "object", "properties": { "jobSuccessScore": { "type": "integer", "minimum": 0, "maximum": 100 }, "completedJobs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalHours": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "totalEarningsUsd": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "hourlyRateUsd": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "talentBadge": { "type": "string", "enum": [ "rising-talent", "top-rated", "top-rated-plus", "expert-vetted" ] }, "skills": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "source": { "type": "string", "enum": [ "manual", "reviewed-import" ] }, "provider": { "type": "string", "enum": [ "moxlade" ] }, "fetchedAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "source", "updatedAt" ], "additionalProperties": true } }, "required": [ "profileUrl", "displayName", "headline", "description", "city", "upwork" ], "additionalProperties": true }, "fetchedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "statusUrl", "type", "status", "upworkImportId", "profile", "fetchedAt" ], "additionalProperties": true }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "statusUrl": { "type": "string", "minLength": 0, "maxLength": 2048 }, "type": { "type": "string", "enum": [ "upwork" ] }, "status": { "type": "string", "enum": [ "failed" ] }, "upworkImportId": { "type": "string", "format": "uuid" }, "message": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "id", "statusUrl", "type", "status", "upworkImportId", "message" ], "additionalProperties": true } ] } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "profiles:read" ], "x-actor-capability": "manager", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/agent-profiles/scrape": { "post": { "operationId": "scrapeLinkedInProfile", "tags": [ "Profiles" ], "summary": "Import public LinkedIn details (legacy)", "deprecated": true, "x-replacement-operation-id": "startProfileImport", "description": "Deprecated: use POST /agent-profiles/imports with type=linkedin. This compatibility route preserves its original response and permissions. A duplicate check runs before the paid scraper. This can incur provider costs; no scraping guarantee.\n\nActor capability: member. Required token scopes: profiles:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Scraped profile data for review; this does not create a listing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "lastName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "displayName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "headline": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "about": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "photoUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "bannerUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "city": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "currentCompany": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "followers": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "connections": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "gender": { "type": "null" }, "isVerified": { "type": [ "boolean", "null" ] }, "verifications": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "description": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "verifiedAt": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "type", "description", "verifiedAt" ], "additionalProperties": true } }, "firstRoleYear": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "totalExperienceYears": { "type": [ "number", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "experiences": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "companyName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "companyLogoUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "companyLinkedinUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "employmentType": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "startDate": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "endDate": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "duration": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "location": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "workMode": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "description": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "title", "companyName", "companyLogoUrl", "companyLinkedinUrl", "employmentType", "startDate", "endDate", "duration", "location", "workMode", "description" ], "additionalProperties": true } } }, "required": [ "displayName", "headline", "about", "photoUrl", "bannerUrl", "city", "currentCompany", "followers", "connections", "gender", "isVerified", "verifications", "firstRoleYear", "totalExperienceYears", "experiences" ], "additionalProperties": true } } } }, "201": { "description": "Scraped profile data for review; this does not create a listing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "lastName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "displayName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "headline": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "about": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "photoUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "bannerUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "city": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "currentCompany": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "followers": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "connections": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "gender": { "type": "null" }, "isVerified": { "type": [ "boolean", "null" ] }, "verifications": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "description": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "verifiedAt": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "type", "description", "verifiedAt" ], "additionalProperties": true } }, "firstRoleYear": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "totalExperienceYears": { "type": [ "number", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "experiences": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "companyName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "companyLogoUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "companyLinkedinUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "employmentType": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "startDate": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "endDate": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "duration": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "location": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "workMode": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "description": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "title", "companyName", "companyLogoUrl", "companyLinkedinUrl", "employmentType", "startDate", "endDate", "duration", "location", "workMode", "description" ], "additionalProperties": true } } }, "required": [ "displayName", "headline", "about", "photoUrl", "bannerUrl", "city", "currentCompany", "followers", "connections", "gender", "isVerified", "verifications", "firstRoleYear", "totalExperienceYears", "experiences" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "excludeProfileId": { "type": "string", "format": "uuid" } }, "required": [ "url" ], "additionalProperties": false } } } }, "x-required-scopes": [ "profiles:write" ], "x-actor-capability": "member", "x-risk": "external", "x-human-required": false, "x-idempotency-required": true } }, "/agent-profiles/upwork-imports": { "post": { "operationId": "startUpworkImport", "tags": [ "Profiles" ], "summary": "Start an Upwork import (legacy)", "deprecated": true, "x-replacement-operation-id": "startProfileImport", "description": "Deprecated: use POST /agent-profiles/imports with type=upwork. This compatibility route preserves its original response.\n\nActor capability: manager. Required token scopes: profiles:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Import job/receipt identifier and status; poll before applying the reviewed result.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending" ] } }, "required": [ "id", "status" ], "additionalProperties": true }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "ready" ] }, "profile": { "type": "object", "properties": { "profileUrl": { "type": "string", "minLength": 0, "maxLength": 5000 }, "displayName": { "type": "string", "minLength": 0, "maxLength": 5000 }, "headline": { "type": "string", "minLength": 0, "maxLength": 5000 }, "description": { "type": "string", "minLength": 0, "maxLength": 5000 }, "city": { "type": "string", "minLength": 0, "maxLength": 5000 }, "upwork": { "type": "object", "properties": { "jobSuccessScore": { "type": "integer", "minimum": 0, "maximum": 100 }, "completedJobs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalHours": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "totalEarningsUsd": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "hourlyRateUsd": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "talentBadge": { "type": "string", "enum": [ "rising-talent", "top-rated", "top-rated-plus", "expert-vetted" ] }, "skills": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "source": { "type": "string", "enum": [ "manual", "reviewed-import" ] }, "provider": { "type": "string", "enum": [ "moxlade" ] }, "fetchedAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "source", "updatedAt" ], "additionalProperties": true } }, "required": [ "profileUrl", "displayName", "headline", "description", "city", "upwork" ], "additionalProperties": true }, "fetchedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "status", "profile", "fetchedAt" ], "additionalProperties": true }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "failed" ] }, "message": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "id", "status", "message" ], "additionalProperties": true } ] } } } }, "201": { "description": "Import job/receipt identifier and status; poll before applying the reviewed result.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending" ] } }, "required": [ "id", "status" ], "additionalProperties": true }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "ready" ] }, "profile": { "type": "object", "properties": { "profileUrl": { "type": "string", "minLength": 0, "maxLength": 5000 }, "displayName": { "type": "string", "minLength": 0, "maxLength": 5000 }, "headline": { "type": "string", "minLength": 0, "maxLength": 5000 }, "description": { "type": "string", "minLength": 0, "maxLength": 5000 }, "city": { "type": "string", "minLength": 0, "maxLength": 5000 }, "upwork": { "type": "object", "properties": { "jobSuccessScore": { "type": "integer", "minimum": 0, "maximum": 100 }, "completedJobs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalHours": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "totalEarningsUsd": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "hourlyRateUsd": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "talentBadge": { "type": "string", "enum": [ "rising-talent", "top-rated", "top-rated-plus", "expert-vetted" ] }, "skills": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "source": { "type": "string", "enum": [ "manual", "reviewed-import" ] }, "provider": { "type": "string", "enum": [ "moxlade" ] }, "fetchedAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "source", "updatedAt" ], "additionalProperties": true } }, "required": [ "profileUrl", "displayName", "headline", "description", "city", "upwork" ], "additionalProperties": true }, "fetchedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "status", "profile", "fetchedAt" ], "additionalProperties": true }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "failed" ] }, "message": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "id", "status", "message" ], "additionalProperties": true } ] } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "requestId": { "type": "string", "format": "uuid" }, "excludeProfileId": { "type": "string", "format": "uuid" } }, "required": [ "url", "requestId" ], "additionalProperties": false } } } }, "x-required-scopes": [ "profiles:write" ], "x-actor-capability": "manager", "x-risk": "external", "x-human-required": false, "x-idempotency-required": true } }, "/agent-profiles/upwork-imports/{id}": { "get": { "operationId": "getUpworkImport", "tags": [ "Profiles" ], "summary": "Read an Upwork import (legacy)", "deprecated": true, "x-replacement-operation-id": "getProfileImport", "description": "Deprecated for new imports. Existing legacy import IDs continue to use this route; new imports use the statusUrl returned by POST /agent-profiles/imports.\n\nActor capability: member. Required token scopes: profiles:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job state, imported public details or failure details; an import receipt is scoped to its organization and creator.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending" ] } }, "required": [ "id", "status" ], "additionalProperties": true }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "ready" ] }, "profile": { "type": "object", "properties": { "profileUrl": { "type": "string", "minLength": 0, "maxLength": 5000 }, "displayName": { "type": "string", "minLength": 0, "maxLength": 5000 }, "headline": { "type": "string", "minLength": 0, "maxLength": 5000 }, "description": { "type": "string", "minLength": 0, "maxLength": 5000 }, "city": { "type": "string", "minLength": 0, "maxLength": 5000 }, "upwork": { "type": "object", "properties": { "jobSuccessScore": { "type": "integer", "minimum": 0, "maximum": 100 }, "completedJobs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalHours": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "totalEarningsUsd": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "hourlyRateUsd": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "talentBadge": { "type": "string", "enum": [ "rising-talent", "top-rated", "top-rated-plus", "expert-vetted" ] }, "skills": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "source": { "type": "string", "enum": [ "manual", "reviewed-import" ] }, "provider": { "type": "string", "enum": [ "moxlade" ] }, "fetchedAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "source", "updatedAt" ], "additionalProperties": true } }, "required": [ "profileUrl", "displayName", "headline", "description", "city", "upwork" ], "additionalProperties": true }, "fetchedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "status", "profile", "fetchedAt" ], "additionalProperties": true }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "failed" ] }, "message": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "id", "status", "message" ], "additionalProperties": true } ] } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "profiles:read" ], "x-actor-capability": "member", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/agent-profiles/upload-photo": { "post": { "operationId": "uploadProfileImage", "tags": [ "Profiles" ], "summary": "Upload a profile image", "description": "Actor capability: member. Required token scopes: profiles:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "{url:string}. Only the current organization's upload location is used.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 0, "maxLength": 2048 } }, "required": [ "url" ], "additionalProperties": false } } } }, "201": { "description": "{url:string}. Only the current organization's upload location is used.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 0, "maxLength": 2048 } }, "required": [ "url" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image": { "type": "string", "minLength": 1, "maxLength": 12000000, "description": "Public image URL or supported image data URL. Existing upload size/type/host checks apply." }, "platform": { "type": "string", "minLength": 1, "maxLength": 80 }, "folder": { "type": "string", "enum": [ "avatars", "banners", "experience-logos" ] } }, "required": [ "image", "platform" ], "additionalProperties": false } } } }, "x-required-scopes": [ "profiles:write" ], "x-actor-capability": "member", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/agent-profiles/default-avatar": { "post": { "operationId": "createDefaultAvatar", "tags": [ "Profiles" ], "summary": "Create an initials avatar", "description": "Actor capability: member. Required token scopes: profiles:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "{url:string}. Platform defaults to linkedin; display name defaults to ?.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 0, "maxLength": 2048 } }, "required": [ "url" ], "additionalProperties": false } } } }, "201": { "description": "{url:string}. Platform defaults to linkedin; display name defaults to ?.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 0, "maxLength": 2048 } }, "required": [ "url" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string", "minLength": 0, "maxLength": 200 }, "platform": { "type": "string", "minLength": 0, "maxLength": 80 } }, "required": [], "additionalProperties": false } } } }, "x-required-scopes": [ "profiles:write" ], "x-actor-capability": "member", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/agent-profiles/{id}/sections": { "get": { "operationId": "getProfileSections", "tags": [ "Profiles" ], "summary": "Read profile sections", "description": "Actor capability: member. Required token scopes: profiles:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Ordered section array for an accessible profile. Hidden/private text is redacted for automation.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 80 }, "icon": { "type": "string", "minLength": 0, "maxLength": 40 }, "bodyType": { "type": "string", "enum": [ "list", "description" ] }, "body": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "items": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 500 }, "maxItems": 50, "minItems": 0 }, "sortOrder": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "format": "uuid" }, "agentProfileId": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "title", "icon", "bodyType", "body", "items", "sortOrder", "id", "agentProfileId", "createdAt", "updatedAt" ], "additionalProperties": true } } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "profiles:read" ], "x-actor-capability": "member", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false }, "put": { "operationId": "replaceProfileSections", "tags": [ "Profiles" ], "summary": "Replace profile sections", "description": "Replacement uses the current service's ordered replace operation. Hidden text is supported by the application but must not be copied into public content.\n\nActor capability: member. Required token scopes: profiles:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "The complete new section collection; an empty list clears the sections.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 80 }, "icon": { "type": "string", "minLength": 0, "maxLength": 40 }, "bodyType": { "type": "string", "enum": [ "list", "description" ] }, "body": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "items": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 500 }, "maxItems": 50, "minItems": 0 }, "sortOrder": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "format": "uuid" }, "agentProfileId": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "title", "icon", "bodyType", "body", "items", "sortOrder", "id", "agentProfileId", "createdAt", "updatedAt" ], "additionalProperties": true } } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sections": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 80 }, "icon": { "type": "string", "minLength": 0, "maxLength": 40 }, "bodyType": { "type": "string", "enum": [ "list", "description" ] }, "body": { "type": "string", "minLength": 0, "maxLength": 5000 }, "items": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 500 }, "maxItems": 50, "minItems": 0 }, "sortOrder": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "title", "icon", "bodyType" ], "additionalProperties": false }, "maxItems": 20, "minItems": 0 } }, "required": [ "sections" ], "additionalProperties": false } } } }, "x-required-scopes": [ "profiles:write" ], "x-actor-capability": "member", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/agent-profiles/bookings": { "get": { "operationId": "listProviderBookings", "tags": [ "Rentals" ], "summary": "List provider rentals", "description": "Default 50, maximum 100. Follow nextCursor with the same search, tenant and resource until null. Creation cutoff excludes later inserts; mutable fields may change between pages. Unsupported search returns 400.\n\nActor capability: member. Required token scopes: rentals:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "See list provider rentals pagination and response notes.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "See list provider rentals pagination and response notes.", "schema": { "type": "string", "minLength": 1, "maxLength": 768 } }, { "name": "search", "in": "query", "required": false, "description": "See list provider rentals pagination and response notes.", "schema": { "type": "string", "minLength": 0, "maxLength": 200 } } ], "responses": { "200": { "description": "{data: bounded bookings summaries[], nextCursor: string | null}. Fetch detail endpoints for full records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agentProfileId": { "type": "string", "format": "uuid" }, "clientUserId": { "type": [ "string", "null" ], "format": "uuid" }, "clientId": { "type": [ "string", "null" ], "format": "uuid" }, "isManual": { "type": "boolean" }, "manualClientName": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "completed", "cancelled" ] }, "paymentStatus": { "type": [ "string", "null" ], "enum": [ "pending", "active", "past_due", "cancelled", "incomplete", null ] }, "priceInCents": { "type": "integer" }, "pricingPeriod": { "type": "string", "enum": [ "day", "week", "month" ] }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": [ "string", "null" ], "format": "date-time" }, "currentPeriodEnd": { "type": [ "string", "null" ], "format": "date-time" }, "cancelledAt": { "type": [ "string", "null" ], "format": "date-time" }, "serviceFeeInCents": { "type": [ "integer", "null" ] }, "ownerPriceInCents": { "type": [ "integer", "null" ] }, "payoutMethod": { "type": "string", "enum": [ "fiat", "crypto" ] }, "profileName": { "type": "string" }, "clientName": { "type": [ "string", "null" ] }, "clientEmail": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "agentProfileId", "clientUserId", "clientId", "isManual", "manualClientName", "status", "paymentStatus", "priceInCents", "pricingPeriod", "startDate", "endDate", "currentPeriodEnd", "cancelledAt", "serviceFeeInCents", "ownerPriceInCents", "payoutMethod", "profileName", "clientName", "clientEmail", "createdAt", "updatedAt" ], "additionalProperties": false }, "maxItems": 100, "minItems": 0 }, "nextCursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 768 } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "rentals:read" ], "x-actor-capability": "member", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/agent-profiles/bookings/manual": { "post": { "operationId": "createManualRental", "tags": [ "Rentals" ], "summary": "Record an off-platform rental", "description": "This records a rental; it does not charge a customer or produce a paid invoice.\n\nActor capability: manager. Required token scopes: rentals:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Created manual booking. clientId is preferred; clientName is a legacy fallback.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "clientUserId": { "type": [ "string", "null" ], "format": "uuid" }, "agentProfileId": { "type": "string", "format": "uuid" }, "isManual": { "type": "boolean" }, "manualClientName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "clientId": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "type": "string", "enum": [ "active", "completed", "cancelled" ] }, "priceInCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "pricingPeriod": { "type": "string", "enum": [ "day", "week", "month" ] }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": [ "string", "null" ], "format": "date-time" }, "notes": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "usagePurpose": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "stripeSubscriptionId": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "stripeSubscriptionItemId": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "stripeCheckoutSessionId": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "paymentStatus": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "serviceFeeInCents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "ownerPriceInCents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "payoutMethod": { "type": "string", "enum": [ "fiat", "crypto" ] }, "currentPeriodEnd": { "type": [ "string", "null" ], "format": "date-time" }, "cancelledAt": { "type": [ "string", "null" ], "format": "date-time" }, "cancelledBy": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "refundedAmountCents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "refundedAt": { "type": [ "string", "null" ], "format": "date-time" }, "previousAgentProfileId": { "type": [ "string", "null" ], "format": "uuid" }, "swappedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "clientUserId", "agentProfileId", "isManual", "manualClientName", "clientId", "status", "priceInCents", "pricingPeriod", "startDate", "endDate", "notes", "usagePurpose", "stripeSubscriptionId", "stripeSubscriptionItemId", "stripeCheckoutSessionId", "paymentStatus", "serviceFeeInCents", "ownerPriceInCents", "payoutMethod", "currentPeriodEnd", "cancelledAt", "cancelledBy", "refundedAmountCents", "refundedAt", "previousAgentProfileId", "swappedAt", "createdAt", "updatedAt" ], "additionalProperties": true } } } }, "201": { "description": "Created manual booking. clientId is preferred; clientName is a legacy fallback.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "clientUserId": { "type": [ "string", "null" ], "format": "uuid" }, "agentProfileId": { "type": "string", "format": "uuid" }, "isManual": { "type": "boolean" }, "manualClientName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "clientId": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "type": "string", "enum": [ "active", "completed", "cancelled" ] }, "priceInCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "pricingPeriod": { "type": "string", "enum": [ "day", "week", "month" ] }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": [ "string", "null" ], "format": "date-time" }, "notes": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "usagePurpose": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "stripeSubscriptionId": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "stripeSubscriptionItemId": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "stripeCheckoutSessionId": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "paymentStatus": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "serviceFeeInCents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "ownerPriceInCents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "payoutMethod": { "type": "string", "enum": [ "fiat", "crypto" ] }, "currentPeriodEnd": { "type": [ "string", "null" ], "format": "date-time" }, "cancelledAt": { "type": [ "string", "null" ], "format": "date-time" }, "cancelledBy": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "refundedAmountCents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "refundedAt": { "type": [ "string", "null" ], "format": "date-time" }, "previousAgentProfileId": { "type": [ "string", "null" ], "format": "uuid" }, "swappedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "clientUserId", "agentProfileId", "isManual", "manualClientName", "clientId", "status", "priceInCents", "pricingPeriod", "startDate", "endDate", "notes", "usagePurpose", "stripeSubscriptionId", "stripeSubscriptionItemId", "stripeCheckoutSessionId", "paymentStatus", "serviceFeeInCents", "ownerPriceInCents", "payoutMethod", "currentPeriodEnd", "cancelledAt", "cancelledBy", "refundedAmountCents", "refundedAt", "previousAgentProfileId", "swappedAt", "createdAt", "updatedAt" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentProfileId": { "type": "string", "format": "uuid" }, "priceInCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": [ "string", "null" ], "format": "date-time" }, "clientId": { "type": "string", "format": "uuid" }, "clientName": { "type": "string", "minLength": 0, "maxLength": 120 } }, "required": [ "agentProfileId", "priceInCents", "startDate" ], "additionalProperties": false } } } }, "x-required-scopes": [ "rentals:write" ], "x-actor-capability": "manager", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/agent-profiles/bookings/{id}/end-manual": { "post": { "operationId": "endManualBooking", "tags": [ "Rentals" ], "summary": "End a manual booking", "description": "Actor capability: manager. Required token scopes: rentals:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Ended manual booking; a paid Stripe rental cannot use this action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "201": { "description": "Ended manual booking; a paid Stripe rental cannot use this action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "rentals:write" ], "x-actor-capability": "manager", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/agent-profiles/{id}/cancel-rental": { "post": { "operationId": "cancelRental", "tags": [ "Rentals" ], "summary": "Cancel a provider rental", "description": "scheduled cancels at renewal; immediate ends and follows service refund rules; release ends without refund. past_due Stripe rentals end immediately without refund. Existing organization/profile permission checks apply.\n\nActor capability: member. Required token scopes: rentals:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Rental cancellation result.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "clientUserId": { "type": [ "string", "null" ], "format": "uuid" }, "agentProfileId": { "type": "string", "format": "uuid" }, "isManual": { "type": "boolean" }, "manualClientName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "clientId": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "type": "string", "enum": [ "active", "completed", "cancelled" ] }, "priceInCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "pricingPeriod": { "type": "string", "enum": [ "day", "week", "month" ] }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": [ "string", "null" ], "format": "date-time" }, "notes": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "usagePurpose": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "stripeSubscriptionId": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "stripeSubscriptionItemId": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "stripeCheckoutSessionId": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "paymentStatus": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "serviceFeeInCents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "ownerPriceInCents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "payoutMethod": { "type": "string", "enum": [ "fiat", "crypto" ] }, "currentPeriodEnd": { "type": [ "string", "null" ], "format": "date-time" }, "cancelledAt": { "type": [ "string", "null" ], "format": "date-time" }, "cancelledBy": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "refundedAmountCents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "refundedAt": { "type": [ "string", "null" ], "format": "date-time" }, "previousAgentProfileId": { "type": [ "string", "null" ], "format": "uuid" }, "swappedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "clientUserId", "agentProfileId", "isManual", "manualClientName", "clientId", "status", "priceInCents", "pricingPeriod", "startDate", "endDate", "notes", "usagePurpose", "stripeSubscriptionId", "stripeSubscriptionItemId", "stripeCheckoutSessionId", "paymentStatus", "serviceFeeInCents", "ownerPriceInCents", "payoutMethod", "currentPeriodEnd", "cancelledAt", "cancelledBy", "refundedAmountCents", "refundedAt", "previousAgentProfileId", "swappedAt", "createdAt", "updatedAt" ], "additionalProperties": true }, { "type": "object", "properties": { "message": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "message" ], "additionalProperties": true } ] } } } }, "201": { "description": "Rental cancellation result.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "clientUserId": { "type": [ "string", "null" ], "format": "uuid" }, "agentProfileId": { "type": "string", "format": "uuid" }, "isManual": { "type": "boolean" }, "manualClientName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "clientId": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "type": "string", "enum": [ "active", "completed", "cancelled" ] }, "priceInCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "pricingPeriod": { "type": "string", "enum": [ "day", "week", "month" ] }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": [ "string", "null" ], "format": "date-time" }, "notes": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "usagePurpose": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "stripeSubscriptionId": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "stripeSubscriptionItemId": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "stripeCheckoutSessionId": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "paymentStatus": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "serviceFeeInCents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "ownerPriceInCents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "payoutMethod": { "type": "string", "enum": [ "fiat", "crypto" ] }, "currentPeriodEnd": { "type": [ "string", "null" ], "format": "date-time" }, "cancelledAt": { "type": [ "string", "null" ], "format": "date-time" }, "cancelledBy": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "refundedAmountCents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "refundedAt": { "type": [ "string", "null" ], "format": "date-time" }, "previousAgentProfileId": { "type": [ "string", "null" ], "format": "uuid" }, "swappedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "clientUserId", "agentProfileId", "isManual", "manualClientName", "clientId", "status", "priceInCents", "pricingPeriod", "startDate", "endDate", "notes", "usagePurpose", "stripeSubscriptionId", "stripeSubscriptionItemId", "stripeCheckoutSessionId", "paymentStatus", "serviceFeeInCents", "ownerPriceInCents", "payoutMethod", "currentPeriodEnd", "cancelledAt", "cancelledBy", "refundedAmountCents", "refundedAt", "previousAgentProfileId", "swappedAt", "createdAt", "updatedAt" ], "additionalProperties": true }, { "type": "object", "properties": { "message": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "message" ], "additionalProperties": true } ] } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "scheduled", "immediate", "release" ], "default": "scheduled" } }, "required": [], "additionalProperties": false } } } }, "x-required-scopes": [ "rentals:write" ], "x-actor-capability": "member", "x-risk": "financial", "x-human-required": false, "x-idempotency-required": true } }, "/agent-profiles/{id}/resume-rental": { "post": { "operationId": "resumeRental", "tags": [ "Rentals" ], "summary": "Resume provider-scheduled renewal", "description": "Actor capability: member. Required token scopes: rentals:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Resumed Stripe subscription; client-scheduled cancellation can only be resumed by the client.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "message" ], "additionalProperties": true } } } }, "201": { "description": "Resumed Stripe subscription; client-scheduled cancellation can only be resumed by the client.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "message" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "rentals:write" ], "x-actor-capability": "member", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/agent-profiles/{id}/end-manual-rental": { "post": { "operationId": "endManualProfileRental", "tags": [ "Rentals" ], "summary": "Relist a manually rented profile", "description": "Actor capability: manager. Required token scopes: rentals:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Ended manual rental and profile availability; rejects a paid Stripe rental.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "201": { "description": "Ended manual rental and profile availability; rejects a paid Stripe rental.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "rentals:write" ], "x-actor-capability": "manager", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/agent-profiles/{id}/swap-rental": { "post": { "operationId": "swapRentalProfile", "tags": [ "Rentals" ], "summary": "Replace the profile in a rental", "description": "No new customer charge. If no active rental exists the legacy service may return a message instead of a booking.\n\nActor capability: member. Required token scopes: rentals:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Replacement rental result. Both profiles must be accessible, in the same organization and have the same price.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "message" ], "additionalProperties": false }, { "type": "object", "properties": { "message": { "type": "string", "minLength": 0, "maxLength": 5000 }, "bookingId": { "type": "string", "format": "uuid" }, "newProfileId": { "type": "string", "format": "uuid" }, "previousProfileId": { "type": "string", "format": "uuid" } }, "required": [ "message", "bookingId", "newProfileId", "previousProfileId" ], "additionalProperties": true } ] } } } }, "201": { "description": "Replacement rental result. Both profiles must be accessible, in the same organization and have the same price.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "message" ], "additionalProperties": false }, { "type": "object", "properties": { "message": { "type": "string", "minLength": 0, "maxLength": 5000 }, "bookingId": { "type": "string", "format": "uuid" }, "newProfileId": { "type": "string", "format": "uuid" }, "previousProfileId": { "type": "string", "format": "uuid" } }, "required": [ "message", "bookingId", "newProfileId", "previousProfileId" ], "additionalProperties": true } ] } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "newProfileId": { "type": "string", "format": "uuid" } }, "required": [ "newProfileId" ], "additionalProperties": false } } } }, "x-required-scopes": [ "rentals:write" ], "x-actor-capability": "member", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/agent-profiles/{id}/extend-rental": { "post": { "operationId": "creditRentalDays", "tags": [ "Rentals" ], "summary": "Apply a goodwill rental credit", "description": "Calculates a monetary credit for 1–30 days. It does not move the subscription renewal date. No active rental can return a service message.\n\nActor capability: member. Required token scopes: rentals:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Goodwill monetary credit result.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "message" ], "additionalProperties": false }, { "type": "object", "properties": { "message": { "type": "string", "minLength": 0, "maxLength": 5000 }, "bookingId": { "type": "string", "format": "uuid" }, "days": { "type": "integer", "minimum": 1, "maximum": 30 }, "creditCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "message", "bookingId", "days", "creditCents" ], "additionalProperties": true } ] } } } }, "201": { "description": "Goodwill monetary credit result.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "message" ], "additionalProperties": false }, { "type": "object", "properties": { "message": { "type": "string", "minLength": 0, "maxLength": 5000 }, "bookingId": { "type": "string", "format": "uuid" }, "days": { "type": "integer", "minimum": 1, "maximum": 30 }, "creditCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "message", "bookingId", "days", "creditCents" ], "additionalProperties": true } ] } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "days": { "type": "integer", "minimum": 1, "maximum": 30 } }, "required": [ "days" ], "additionalProperties": false } } } }, "x-required-scopes": [ "rentals:write" ], "x-actor-capability": "member", "x-risk": "financial", "x-human-required": false, "x-idempotency-required": true } }, "/clients": { "get": { "operationId": "listClients", "tags": [ "Clients" ], "summary": "Search off-platform clients", "description": "Default 50, maximum 100. Follow nextCursor with the same search, tenant and resource until null. Creation cutoff excludes later inserts; mutable fields may change between pages. Unsupported search returns 400.\n\nActor capability: manager. Required token scopes: clients:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "See search off-platform clients pagination and response notes.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "See search off-platform clients pagination and response notes.", "schema": { "type": "string", "minLength": 1, "maxLength": 768 } }, { "name": "search", "in": "query", "required": false, "description": "See search off-platform clients pagination and response notes.", "schema": { "type": "string", "minLength": 0, "maxLength": 200 } } ], "responses": { "200": { "description": "{data: bounded clients summaries[], nextCursor: string | null}. Fetch detail endpoints for full records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "createdById": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "name", "email", "company", "notes", "createdById", "createdAt", "updatedAt" ], "additionalProperties": false }, "maxItems": 100, "minItems": 0 }, "nextCursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 768 } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "clients:read" ], "x-actor-capability": "manager", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false }, "post": { "operationId": "createClient", "tags": [ "Clients" ], "summary": "Save an off-platform client", "description": "Actor capability: manager. Required token scopes: clients:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Created client or the existing same-name client; does not send an invitation or invoice.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 0, "maxLength": 5000 }, "email": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "company": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "notes": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "createdById": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "name" ], "additionalProperties": true } } } }, "201": { "description": "Created client or the existing same-name client; does not send an invitation or invoice.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 0, "maxLength": 5000 }, "email": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "company": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "notes": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "createdById": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "name" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "email": { "type": "string", "format": "email", "maxLength": 200 }, "company": { "type": "string", "minLength": 0, "maxLength": 120 }, "notes": { "type": "string", "minLength": 0, "maxLength": 1000 } }, "required": [ "name" ], "additionalProperties": false } } } }, "x-required-scopes": [ "clients:write" ], "x-actor-capability": "manager", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/org-agents": { "get": { "operationId": "listHostedAgents", "tags": [ "Hosted agents" ], "summary": "List hosted agents", "description": "Default 50, maximum 100. Follow nextCursor with the same search, tenant and resource until null. Creation cutoff excludes later inserts; mutable fields may change between pages. Unsupported search returns 400.\n\nActor capability: manager. Required token scopes: agents:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "See list hosted agents pagination and response notes.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "See list hosted agents pagination and response notes.", "schema": { "type": "string", "minLength": 1, "maxLength": 768 } }, { "name": "search", "in": "query", "required": false, "description": "See list hosted agents pagination and response notes.", "schema": { "type": "string", "minLength": 0, "maxLength": 200 } } ], "responses": { "200": { "description": "{data: bounded org-agents summaries[], nextCursor: string | null}. Fetch detail endpoints for full records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "isManual": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "email", "isManual", "createdAt" ], "additionalProperties": false }, "maxItems": 100, "minItems": 0 }, "nextCursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 768 } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "agents:read" ], "x-actor-capability": "manager", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/org-agents/manual": { "post": { "operationId": "createManualAgent", "tags": [ "Hosted agents" ], "summary": "Add an agent paid off-platform", "description": "Actor capability: manager. Required token scopes: agents:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Agent record; without a wallet payroll remains manually payable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "email": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "id", "name", "email" ], "additionalProperties": true } } } }, "201": { "description": "Agent record; without a wallet payroll remains manually payable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "email": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "id", "name", "email" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 200 }, "name": { "type": "string", "minLength": 0, "maxLength": 120 }, "walletAddress": { "type": "string", "minLength": 0, "maxLength": 42, "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Optional Base USDC receiving wallet." } }, "required": [ "email" ], "additionalProperties": false } } } }, "x-required-scopes": [ "agents:write" ], "x-actor-capability": "manager", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/org-agents/new-count": { "get": { "operationId": "getNewAgentCount", "tags": [ "Hosted agents" ], "summary": "Count unseen agents", "description": "Actor capability: manager. Required token scopes: agents:read.", "security": [ { "organizationToken": [] } ], "parameters": [], "responses": { "200": { "description": "New-agent count.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "count" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "agents:read" ], "x-actor-capability": "manager", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/org-agents/mark-viewed": { "post": { "operationId": "markAgentsViewed", "tags": [ "Hosted agents" ], "summary": "Mark agents viewed", "description": "Actor capability: manager. Required token scopes: agents:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Updated viewed marker.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": true } } } }, "201": { "description": "Updated viewed marker.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "agents:write" ], "x-actor-capability": "manager", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/org-agents/assignable-accounts": { "get": { "operationId": "listAssignableAccounts", "tags": [ "Hosted agents" ], "summary": "List assignable accounts", "description": "Default 50, maximum 100. Follow nextCursor with the same search, tenant and resource until null. Creation cutoff excludes later inserts; mutable fields may change between pages. Unsupported search returns 400.\n\nActor capability: manager. Required token scopes: agents:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "See list assignable accounts pagination and response notes.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "See list assignable accounts pagination and response notes.", "schema": { "type": "string", "minLength": 1, "maxLength": 768 } }, { "name": "search", "in": "query", "required": false, "description": "See list assignable accounts pagination and response notes.", "schema": { "type": "string", "minLength": 0, "maxLength": 200 } } ], "responses": { "200": { "description": "{data: bounded assignable-accounts summaries[], nextCursor: string | null}. Fetch detail endpoints for full records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "displayName": { "type": "string" }, "platform": { "type": "string", "enum": [ "linkedin", "facebook", "x", "upwork", "reddit" ] }, "operatingAgentId": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "id", "displayName", "platform", "operatingAgentId" ], "additionalProperties": false }, "maxItems": 100, "minItems": 0 }, "nextCursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 768 } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "agents:read" ], "x-actor-capability": "manager", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/org-agents/{id}": { "get": { "operationId": "getHostedAgent", "tags": [ "Hosted agents" ], "summary": "Read a hosted agent", "description": "Actor capability: manager. Required token scopes: agents:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Agent details scoped to the token organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "email": { "type": "string", "minLength": 0, "maxLength": 5000 }, "isManual": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "email", "isManual", "createdAt" ], "additionalProperties": true }, "payoutMethods": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "type": { "type": "string", "minLength": 0, "maxLength": 5000 }, "label": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "isDefault": { "type": "boolean" }, "enabled": { "type": "boolean" }, "walletAddress": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "walletChain": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "walletCurrency": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "bridgeCustomerId": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "bridgeKycStatus": { "type": "string", "enum": [ "not_started", "pending", "active", "rejected" ] }, "bridgePayoutMethodId": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "userId", "type", "label", "isDefault", "enabled", "walletAddress", "walletChain", "walletCurrency", "bridgeCustomerId", "bridgeKycStatus", "bridgePayoutMethodId", "createdAt", "updatedAt" ], "additionalProperties": true } }, "payouts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 0, "maxLength": 5000 }, "status": { "type": "string", "minLength": 0, "maxLength": 5000 }, "transferId": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "createdAt": { "type": "string", "format": "date-time" }, "paidAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "amountCents", "currency", "status", "transferId", "createdAt", "paidAt" ], "additionalProperties": true } }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "displayName": { "type": "string", "minLength": 0, "maxLength": 5000 }, "photoUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "platform": { "type": "string", "minLength": 0, "maxLength": 5000 }, "status": { "type": "string", "minLength": 0, "maxLength": 5000 }, "priceInCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "agentPayoutRateCents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "monthlyExpenses": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 0, "maxLength": 5000 }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "label", "amountCents" ], "additionalProperties": true } } }, "required": [ "id", "displayName", "photoUrl", "platform", "status", "priceInCents", "agentPayoutRateCents", "monthlyExpenses" ], "additionalProperties": true } } }, "required": [ "agent", "payoutMethods", "payouts", "accounts" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "agents:read" ], "x-actor-capability": "manager", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/org-agents/{id}/assign": { "post": { "operationId": "assignHostedAgent", "tags": [ "Hosted agents" ], "summary": "Assign an account to an agent", "description": "Actor capability: manager. Required token scopes: agents:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Updated account assignment; both resources must belong to the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": true } } } }, "201": { "description": "Updated account assignment; both resources must belong to the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profileId": { "type": "string", "format": "uuid" } }, "required": [ "profileId" ], "additionalProperties": false } } } }, "x-required-scopes": [ "agents:write" ], "x-actor-capability": "manager", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/org-agents/unassign": { "post": { "operationId": "unassignHostedAgent", "tags": [ "Hosted agents" ], "summary": "Remove an account assignment", "description": "Actor capability: manager. Required token scopes: agents:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Updated account assignment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": true } } } }, "201": { "description": "Updated account assignment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profileId": { "type": "string", "format": "uuid" } }, "required": [ "profileId" ], "additionalProperties": false } } } }, "x-required-scopes": [ "agents:write" ], "x-actor-capability": "manager", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/org-agents/accounts/{profileId}/economics": { "patch": { "operationId": "updateAccountEconomics", "tags": [ "Hosted agents" ], "summary": "Edit agent rate and account costs", "description": "Actor capability: manager. Required token scopes: agents:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "profileId", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Updated economics. A null agentPayoutRateCents clears the override.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentPayoutRateCents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "monthlyExpenses": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 0, "maxLength": 60 }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "label", "amountCents" ], "additionalProperties": false }, "maxItems": 20, "minItems": 0 } }, "required": [], "additionalProperties": false } } } }, "x-required-scopes": [ "agents:write" ], "x-actor-capability": "manager", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/rule-templates": { "get": { "operationId": "listRuleTemplates", "tags": [ "Rule templates" ], "summary": "List organization rules", "description": "Default 50, maximum 100. Follow nextCursor with the same search, tenant and resource until null. Creation cutoff excludes later inserts; mutable fields may change between pages. Unsupported search returns 400.\n\nActor capability: member. Required token scopes: profiles:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "See list organization rules pagination and response notes.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "See list organization rules pagination and response notes.", "schema": { "type": "string", "minLength": 1, "maxLength": 768 } }, { "name": "search", "in": "query", "required": false, "description": "See list organization rules pagination and response notes.", "schema": { "type": "string", "minLength": 0, "maxLength": 200 } } ], "responses": { "200": { "description": "{data: bounded rules summaries[], nextCursor: string | null}. Fetch detail endpoints for full records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "icon": { "type": "string" }, "bodyType": { "type": "string", "enum": [ "list", "description" ] }, "body": { "type": [ "string", "null" ] }, "rules": { "type": "array", "items": { "type": "string" } }, "createdById": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "icon", "bodyType", "body", "rules", "createdById", "createdAt", "updatedAt" ], "additionalProperties": false }, "maxItems": 100, "minItems": 0 }, "nextCursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 768 } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "profiles:read" ], "x-actor-capability": "member", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false }, "post": { "operationId": "createRuleTemplate", "tags": [ "Rule templates" ], "summary": "Create a rule template", "description": "Actor capability: member. Required token scopes: profiles:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Created rule template.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "icon": { "type": "string", "minLength": 0, "maxLength": 40 }, "bodyType": { "type": "string", "enum": [ "list", "description" ] }, "rules": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 500 }, "maxItems": 50, "minItems": 0 }, "body": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "createdById": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "name", "icon", "bodyType", "rules", "body", "id", "organizationId", "createdById", "createdAt", "updatedAt" ], "additionalProperties": true } } } }, "201": { "description": "Created rule template.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "icon": { "type": "string", "minLength": 0, "maxLength": 40 }, "bodyType": { "type": "string", "enum": [ "list", "description" ] }, "rules": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 500 }, "maxItems": 50, "minItems": 0 }, "body": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "createdById": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "name", "icon", "bodyType", "rules", "body", "id", "organizationId", "createdById", "createdAt", "updatedAt" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "icon": { "type": "string", "minLength": 0, "maxLength": 40 }, "bodyType": { "type": "string", "enum": [ "list", "description" ] }, "rules": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 500 }, "maxItems": 50, "minItems": 0 }, "body": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "name", "icon", "bodyType" ], "additionalProperties": false } } } }, "x-required-scopes": [ "profiles:write" ], "x-actor-capability": "member", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/rule-templates/{id}": { "patch": { "operationId": "updateRuleTemplate", "tags": [ "Rule templates" ], "summary": "Edit a rule template", "description": "Actor capability: member. Required token scopes: profiles:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Updated rule template.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "icon": { "type": "string", "minLength": 0, "maxLength": 40 }, "bodyType": { "type": "string", "enum": [ "list", "description" ] }, "rules": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 500 }, "maxItems": 50, "minItems": 0 }, "body": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "createdById": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "name", "icon", "bodyType", "rules", "body", "id", "organizationId", "createdById", "createdAt", "updatedAt" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "icon": { "type": "string", "minLength": 0, "maxLength": 40 }, "bodyType": { "type": "string", "enum": [ "list", "description" ] }, "rules": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 500 }, "maxItems": 50, "minItems": 0 }, "body": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [], "additionalProperties": false } } } }, "x-required-scopes": [ "profiles:write" ], "x-actor-capability": "member", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true }, "delete": { "operationId": "deleteRuleTemplate", "tags": [ "Rule templates" ], "summary": "Delete a rule template", "description": "Actor capability: member. Required token scopes: profiles:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Deletion result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "profiles:write" ], "x-actor-capability": "member", "x-risk": "destructive", "x-human-required": false, "x-idempotency-required": true } }, "/auth/organization": { "get": { "operationId": "getOrganization", "tags": [ "Organization" ], "summary": "Read organization settings and API identity", "description": "Actor capability: owner. Required token scopes: organization:read.", "security": [ { "organizationToken": [] } ], "parameters": [], "responses": { "200": { "description": "Current organization business settings and issuing actor identity. Use actor.id when ignoring your bot's own chat-message events.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 0, "maxLength": 5000 }, "logoUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "industry": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "description": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "actor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "id", "email" ], "additionalProperties": false } }, "required": [ "id", "name", "actor" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "organization:read" ], "x-actor-capability": "owner", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false }, "patch": { "operationId": "updateOrganization", "tags": [ "Organization" ], "summary": "Edit organization details", "description": "Actor capability: manager. Required token scopes: organization:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Updated authenticated owner/workspace snapshot; empty/null logo, industry and description clear those values.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "minLength": 0, "maxLength": 5000 }, "name": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "avatarUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "onboardingFlags": { "type": "object", "additionalProperties": true, "description": "Platform scrape metadata. Keep credentials out of this field." }, "notificationPreferences": { "type": "object", "additionalProperties": true, "description": "Platform scrape metadata. Keep credentials out of this field." }, "role": { "type": "string", "minLength": 0, "maxLength": 5000 }, "accountType": { "type": "string", "minLength": 0, "maxLength": 5000 }, "orgRole": { "type": "string", "minLength": 0, "maxLength": 5000 }, "isEmailVerified": { "type": "boolean" }, "registrationStatus": { "type": "string", "minLength": 0, "maxLength": 5000 }, "createdAt": { "type": "string", "format": "date-time" }, "workspaceId": { "type": [ "string", "null" ], "format": "uuid" }, "workspaceName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "workspaceLogoUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "workspaceIndustry": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "workspaceDescription": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "permissions": { "type": "object", "properties": { "orgRole": { "type": "string", "minLength": 0, "maxLength": 5000 }, "accountType": { "type": "string", "minLength": 0, "maxLength": 5000 }, "pages": { "type": "object", "additionalProperties": { "type": "boolean" } }, "actions": { "type": "object", "additionalProperties": { "type": "boolean" } }, "assignedProfileIds": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } } }, "required": [ "orgRole", "accountType", "pages", "actions", "assignedProfileIds" ], "additionalProperties": true } }, "required": [ "id", "email", "name", "avatarUrl", "onboardingFlags", "notificationPreferences", "role", "accountType", "orgRole", "isEmailVerified", "registrationStatus", "createdAt", "workspaceId", "workspaceName", "workspaceLogoUrl", "workspaceIndustry", "workspaceDescription", "permissions" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "logoUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 2048 }, "industry": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 200 }, "description": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [], "additionalProperties": false } } } }, "x-required-scopes": [ "organization:write" ], "x-actor-capability": "manager", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/auth/team": { "get": { "operationId": "getOrganizationTeam", "tags": [ "Team" ], "summary": "List organization team members", "description": "Default 50, maximum 100. Follow nextCursor with the same search, tenant and resource until null. Creation cutoff excludes later inserts; mutable fields may change between pages. Unsupported search returns 400.\n\nActor capability: owner. Required token scopes: team:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "See list organization team members pagination and response notes.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "See list organization team members pagination and response notes.", "schema": { "type": "string", "minLength": 1, "maxLength": 768 } }, { "name": "search", "in": "query", "required": false, "description": "See list organization team members pagination and response notes.", "schema": { "type": "string", "minLength": 0, "maxLength": 200 } } ], "responses": { "200": { "description": "{data: bounded team summaries[], nextCursor: string | null}. Fetch detail endpoints for full records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "isManual": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "orgRole": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "accountType": { "type": "string", "enum": [ "individual", "organization" ] }, "orgChatAccess": { "type": "boolean" }, "canWithdraw": { "type": "boolean" }, "canPayAgents": { "type": "boolean" }, "avatarUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "isManual", "createdAt", "orgRole", "accountType", "orgChatAccess", "canWithdraw", "canPayAgents", "avatarUrl" ], "additionalProperties": false }, "maxItems": 100, "minItems": 0 }, "nextCursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 768 } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "team:read" ], "x-actor-capability": "owner", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/auth/team/invitations": { "get": { "operationId": "listTeamInvitations", "tags": [ "Team" ], "summary": "List pending team invitations", "description": "Default 50, maximum 100. Follow nextCursor with the same search, tenant and resource until null. Creation cutoff excludes later inserts; mutable fields may change between pages. Unsupported search returns 400.\n\nActor capability: owner. Required token scopes: team:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "See list pending team invitations pagination and response notes.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "See list pending team invitations pagination and response notes.", "schema": { "type": "string", "minLength": 1, "maxLength": 768 } }, { "name": "search", "in": "query", "required": false, "description": "See list pending team invitations pagination and response notes.", "schema": { "type": "string", "minLength": 0, "maxLength": 200 } } ], "responses": { "200": { "description": "{data: bounded team-invitations summaries[], nextCursor: string | null}. Fetch detail endpoints for full records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "status": { "type": "string", "enum": [ "pending" ] }, "orgRole": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "email", "status", "orgRole", "expiresAt", "createdAt" ], "additionalProperties": false }, "maxItems": 100, "minItems": 0 }, "nextCursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 768 } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "team:read" ], "x-actor-capability": "owner", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/auth/team/invite": { "post": { "operationId": "inviteTeamMember", "tags": [ "Team" ], "summary": "Invite a staff member", "description": "Actor capability: owner. Required token scopes: team:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Invitation result. Sends an invitation email; invite acceptance stays an interactive user flow.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "message" ], "additionalProperties": true } } } }, "201": { "description": "Invitation result. Sends an invitation email; invite acceptance stays an interactive user flow.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "message" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 200 }, "orgRole": { "type": "string", "enum": [ "admin", "member" ] } }, "required": [ "email" ], "additionalProperties": false } } } }, "x-required-scopes": [ "team:write" ], "x-actor-capability": "owner", "x-risk": "external", "x-human-required": false, "x-idempotency-required": true } }, "/auth/team/cancel-invite": { "post": { "operationId": "cancelTeamInvitation", "tags": [ "Team" ], "summary": "Cancel a staff invitation", "description": "Actor capability: owner. Required token scopes: team:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Canceled invitation result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "message" ], "additionalProperties": true } } } }, "201": { "description": "Canceled invitation result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "message" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "inviteId": { "type": "string", "format": "uuid" } }, "required": [ "inviteId" ], "additionalProperties": false } } } }, "x-required-scopes": [ "team:write" ], "x-actor-capability": "owner", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/auth/team/remove-member": { "post": { "operationId": "removeTeamMember", "tags": [ "Team" ], "summary": "Remove a staff member", "description": "Actor capability: owner. Required token scopes: team:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Removal result; removes this organization's membership, not an arbitrary user account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "message" ], "additionalProperties": true } } } }, "201": { "description": "Removal result; removes this organization's membership, not an arbitrary user account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "message" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "memberId": { "type": "string", "format": "uuid" } }, "required": [ "memberId" ], "additionalProperties": false } } } }, "x-required-scopes": [ "team:write" ], "x-actor-capability": "owner", "x-risk": "destructive", "x-human-required": false, "x-idempotency-required": true } }, "/auth/team/{memberId}/role": { "patch": { "operationId": "changeMemberRole", "tags": [ "Team" ], "summary": "Change a staff role", "description": "Actor capability: owner. Required token scopes: team:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "memberId", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Updated staff role; owner transfer is not supported by this action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "message" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "orgRole": { "type": "string", "enum": [ "admin", "member" ] } }, "required": [ "orgRole" ], "additionalProperties": false } } } }, "x-required-scopes": [ "team:write" ], "x-actor-capability": "owner", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/auth/team/{memberId}/grant": { "patch": { "operationId": "setMemberGrant", "tags": [ "Team" ], "summary": "Set a staff permission", "description": "Actor capability: owner. Required token scopes: team:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "memberId", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Updated grant; hosted agents cannot receive organization-staff grants.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "message" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "grant": { "type": "string", "enum": [ "orgChatAccess", "canWithdraw", "canPayAgents" ] }, "enabled": { "type": "boolean" } }, "required": [ "grant", "enabled" ], "additionalProperties": false } } } }, "x-required-scopes": [ "team:write" ], "x-actor-capability": "owner", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/auth/team/{memberId}/profiles": { "get": { "operationId": "getMemberProfiles", "tags": [ "Team" ], "summary": "Read staff profile assignments", "description": "Default 50, maximum 100. Follow nextCursor with the same search, tenant and resource until null. Creation cutoff excludes later inserts; mutable fields may change between pages. Unsupported search returns 400.\n\nActor capability: owner. Required token scopes: team:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "memberId", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "See read staff profile assignments pagination and response notes.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "See read staff profile assignments pagination and response notes.", "schema": { "type": "string", "minLength": 1, "maxLength": 768 } }, { "name": "search", "in": "query", "required": false, "description": "See read staff profile assignments pagination and response notes.", "schema": { "type": "string", "minLength": 0, "maxLength": 200 } } ], "responses": { "200": { "description": "{data: bounded member-profiles summaries[], nextCursor: string | null}. Fetch detail endpoints for full records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agentProfileId": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "agentProfileId", "createdAt" ], "additionalProperties": false }, "maxItems": 100, "minItems": 0 }, "nextCursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 768 } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "team:read" ], "x-actor-capability": "owner", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false }, "put": { "operationId": "assignMemberProfiles", "tags": [ "Team" ], "summary": "Replace staff profile assignments", "description": "Actor capability: owner. Required token scopes: team:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "memberId", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Updated assignment set; empty list removes assignments.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 0, "maxLength": 5000 }, "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "message", "count" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profileIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 1000, "minItems": 0 } }, "required": [ "profileIds" ], "additionalProperties": false } } } }, "x-required-scopes": [ "team:write" ], "x-actor-capability": "owner", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/auth/chat-auto-messages": { "get": { "operationId": "listChatTemplates", "tags": [ "Chat templates" ], "summary": "List chat automation templates", "description": "Default 50, maximum 100. Follow nextCursor with the same search, tenant and resource until null. Creation cutoff excludes later inserts; mutable fields may change between pages. Unsupported search returns 400.\n\nActor capability: manager. Required token scopes: chat:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "See list chat automation templates pagination and response notes.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "See list chat automation templates pagination and response notes.", "schema": { "type": "string", "minLength": 1, "maxLength": 768 } }, { "name": "search", "in": "query", "required": false, "description": "See list chat automation templates pagination and response notes.", "schema": { "type": "string", "minLength": 0, "maxLength": 200 } } ], "responses": { "200": { "description": "{data: bounded chat-templates summaries[], nextCursor: string | null}. Fetch detail endpoints for full records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "eventKind": { "type": "string" }, "body": { "type": "string" }, "enabled": { "type": "boolean" }, "createdById": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "name", "eventKind", "body", "enabled", "createdById", "createdAt", "updatedAt" ], "additionalProperties": false }, "maxItems": 100, "minItems": 0 }, "nextCursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 768 } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "chat:read" ], "x-actor-capability": "manager", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false }, "post": { "operationId": "createChatTemplate", "tags": [ "Chat templates" ], "summary": "Create a chat automation template", "description": "Actor capability: manager. Required token scopes: chat:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Created template. Enabled templates can send messages when a rental begins.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 0, "maxLength": 5000 }, "eventKind": { "type": "string", "enum": [ "rental_started" ] }, "body": { "type": "string", "minLength": 0, "maxLength": 4000 }, "enabled": { "type": "boolean" }, "createdById": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "name", "eventKind", "body", "enabled", "createdById", "createdAt", "updatedAt" ], "additionalProperties": true } } } }, "201": { "description": "Created template. Enabled templates can send messages when a rental begins.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 0, "maxLength": 5000 }, "eventKind": { "type": "string", "enum": [ "rental_started" ] }, "body": { "type": "string", "minLength": 0, "maxLength": 4000 }, "enabled": { "type": "boolean" }, "createdById": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "name", "eventKind", "body", "enabled", "createdById", "createdAt", "updatedAt" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "eventKind": { "type": "string", "enum": [ "rental_started" ] }, "body": { "type": "string", "minLength": 1, "maxLength": 4000 }, "enabled": { "type": "boolean" } }, "required": [ "name", "eventKind", "body" ], "additionalProperties": false } } } }, "x-required-scopes": [ "chat:write" ], "x-actor-capability": "manager", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/auth/chat-auto-messages/{id}": { "patch": { "operationId": "updateChatTemplate", "tags": [ "Chat templates" ], "summary": "Edit a chat automation template", "description": "Actor capability: manager. Required token scopes: chat:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Updated template.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 0, "maxLength": 5000 }, "eventKind": { "type": "string", "enum": [ "rental_started" ] }, "body": { "type": "string", "minLength": 0, "maxLength": 4000 }, "enabled": { "type": "boolean" }, "createdById": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "name", "eventKind", "body", "enabled", "createdById", "createdAt", "updatedAt" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "eventKind": { "type": "string", "enum": [ "rental_started" ] }, "body": { "type": "string", "minLength": 1, "maxLength": 4000 }, "enabled": { "type": "boolean" } }, "required": [], "additionalProperties": false } } } }, "x-required-scopes": [ "chat:write" ], "x-actor-capability": "manager", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true }, "delete": { "operationId": "deleteChatTemplate", "tags": [ "Chat templates" ], "summary": "Delete a chat automation template", "description": "Actor capability: manager. Required token scopes: chat:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Template deletion result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "message" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "chat:write" ], "x-actor-capability": "manager", "x-risk": "destructive", "x-human-required": false, "x-idempotency-required": true } }, "/volume-discounts": { "get": { "operationId": "getVolumeDiscounts", "tags": [ "Discounts" ], "summary": "Read volume discounts", "description": "Actor capability: manager. Required token scopes: organization:read.", "security": [ { "organizationToken": [] } ], "parameters": [], "responses": { "200": { "description": "Organization's enabled flag and discount tiers. This setting need not be visible in every UI build.", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "minQuantity": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "discountPercent": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "minQuantity", "discountPercent" ], "additionalProperties": true } } }, "required": [ "enabled", "tiers" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "organization:read" ], "x-actor-capability": "manager", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false }, "put": { "operationId": "replaceVolumeDiscounts", "tags": [ "Discounts" ], "summary": "Replace volume discounts", "description": "Actor capability: manager. Required token scopes: organization:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Validated discount ladder. Each minimum quantity must be distinct and discounts must satisfy the existing service rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "minQuantity": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "discountPercent": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "minQuantity", "discountPercent" ], "additionalProperties": true } } }, "required": [ "enabled", "tiers" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "minQuantity": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "discountPercent": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "minQuantity", "discountPercent" ], "additionalProperties": false }, "maxItems": 100, "minItems": 0 } }, "required": [ "enabled" ], "additionalProperties": false } } } }, "x-required-scopes": [ "organization:write" ], "x-actor-capability": "manager", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/analytics/overview": { "get": { "operationId": "getOrganizationAnalytics", "tags": [ "Analytics" ], "summary": "Read the organization overview", "description": "Actor capability: manager. Required token scopes: analytics:read.", "security": [ { "organizationToken": [] } ], "parameters": [], "responses": { "200": { "description": "Current organization analytics overview from the same service as the dashboard. Snapshot figures are not an invented historical time series.", "content": { "application/json": { "schema": { "type": "object", "properties": { "counts": { "type": "object", "properties": { "profiles": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "rented": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "available": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "unlisted": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "verified": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "rentedPct": { "type": "number" }, "availablePct": { "type": "number" }, "unlistedPct": { "type": "number" }, "verifiedPct": { "type": "number" } }, "required": [ "profiles", "rented", "available", "unlisted", "verified", "rentedPct", "availablePct", "unlistedPct", "verifiedPct" ], "additionalProperties": true }, "mrrCents": { "type": "integer" }, "netCents": { "type": "integer" }, "growthPct": { "type": "number" }, "mrrSeries": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 0, "maxLength": 5000 }, "key": { "type": "string", "minLength": 0, "maxLength": 5000 }, "value": { "type": "number" } }, "required": [ "label", "key", "value" ], "additionalProperties": true } }, "netSeries": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 0, "maxLength": 5000 }, "key": { "type": "string", "minLength": 0, "maxLength": 5000 }, "value": { "type": "number" } }, "required": [ "label", "key", "value" ], "additionalProperties": true } }, "topCustomers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "name": { "type": "string", "minLength": 0, "maxLength": 5000 }, "email": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "avatarUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "accounts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "monthlySpendCents": { "type": "integer" }, "totalSpentCents": { "type": "integer" } }, "required": [ "id", "name", "email", "avatarUrl", "accounts", "monthlySpendCents", "totalSpentCents" ], "additionalProperties": true } }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "displayName": { "type": "string", "minLength": 0, "maxLength": 5000 }, "photoUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "status": { "type": "string", "minLength": 0, "maxLength": 5000 }, "monthsRented": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "earningsCents": { "type": "integer" }, "netCents": { "type": "integer" }, "marginPct": { "type": "number" }, "costLines": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 0, "maxLength": 5000 }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "label", "amountCents" ], "additionalProperties": true } }, "costTotalCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "displayName", "photoUrl", "status", "monthsRented", "earningsCents", "netCents", "marginPct", "costLines", "costTotalCents" ], "additionalProperties": true } } }, "required": [ "counts", "mrrCents", "netCents", "growthPct", "mrrSeries", "netSeries", "topCustomers", "accounts" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "analytics:read" ], "x-actor-capability": "manager", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/chat/conversations": { "get": { "operationId": "listConversations", "tags": [ "Chat" ], "summary": "List accessible organization conversations", "description": "limit 1–100 (default 30); pass the opaque cursor exactly as returned. Legacy ISO cursors remain accepted.\n\nActor capability: member. Required token scopes: chat:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "See list accessible organization conversations pagination and response notes.", "schema": { "type": "string", "minLength": 1, "maxLength": 256 } }, { "name": "limit", "in": "query", "required": false, "description": "See list accessible organization conversations pagination and response notes.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "{items:[ConversationSummary],hasMore:boolean,cursor:string|null}. Each item has conversationId, conversationType, otherParticipantId/name/avatar, lastMessage and unreadCount.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "conversationId": { "type": "string", "format": "uuid" }, "conversationType": { "type": "string", "enum": [ "booking", "org_internal", "org_support" ] }, "otherParticipantId": { "type": "string", "format": "uuid" }, "otherParticipantName": { "type": "string", "minLength": 0, "maxLength": 5000 }, "otherParticipantAvatarUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "lastMessage": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "conversationId": { "type": "string", "format": "uuid" }, "senderId": { "type": "string", "format": "uuid" }, "senderName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "body": { "type": "string", "minLength": 0, "maxLength": 5000 }, "kind": { "type": "string", "enum": [ "text", "system", "blocked" ] }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Platform scrape metadata. Keep credentials out of this field." }, "deletedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "clientRequestId": { "type": "string", "format": "uuid" } }, "required": [ "id", "conversationId", "senderId", "body", "kind", "createdAt" ], "additionalProperties": true }, "unreadCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "messaging": { "type": "object", "properties": { "canSend": { "type": "boolean" }, "restrictions": { "type": "array", "items": { "type": "object", "properties": { "party": { "type": "string", "minLength": 0, "maxLength": 5000 }, "subjectType": { "type": "string", "minLength": 0, "maxLength": 5000 }, "subjectId": { "type": "string", "format": "uuid" }, "displayName": { "type": "string", "minLength": 0, "maxLength": 5000 }, "kind": { "type": "string", "enum": [ "banned", "closed" ] }, "reason": { "type": "string", "minLength": 0, "maxLength": 5000 }, "changedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [], "additionalProperties": true } } }, "required": [ "canSend", "restrictions" ], "additionalProperties": true } }, "required": [ "conversationId", "conversationType", "otherParticipantId", "unreadCount" ], "additionalProperties": true } }, "cursor": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 256 }, "hasMore": { "type": "boolean" } }, "required": [ "items", "cursor", "hasMore" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "chat:read" ], "x-actor-capability": "member", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/chat/conversations/{conversationId}/messages": { "get": { "operationId": "listConversationMessages", "tags": [ "Chat" ], "summary": "Read conversation history", "description": "Newest first; limit 1–100 (default 20); nextCursor is a message UUID, null means exhausted.\n\nActor capability: member. Required token scopes: chat:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "description": "See read conversation history pagination and response notes.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "See read conversation history pagination and response notes.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "{messages:[...],nextCursor:string|null,messaging:{...}}. Messages include id, conversationId, senderId, senderName, body, kind, metadata, deletedAt and createdAt.", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "conversationId": { "type": "string", "format": "uuid" }, "senderId": { "type": "string", "format": "uuid" }, "senderName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "body": { "type": "string", "minLength": 0, "maxLength": 5000 }, "kind": { "type": "string", "enum": [ "text", "system", "blocked" ] }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Platform scrape metadata. Keep credentials out of this field." }, "deletedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "clientRequestId": { "type": "string", "format": "uuid" } }, "required": [ "id", "conversationId", "senderId", "body", "kind", "createdAt" ], "additionalProperties": true } }, "nextCursor": { "type": [ "string", "null" ], "format": "uuid" }, "messaging": { "type": "object", "properties": { "canSend": { "type": "boolean" }, "restrictions": { "type": "array", "items": { "type": "object", "properties": { "party": { "type": "string", "minLength": 0, "maxLength": 5000 }, "subjectType": { "type": "string", "minLength": 0, "maxLength": 5000 }, "subjectId": { "type": "string", "format": "uuid" }, "displayName": { "type": "string", "minLength": 0, "maxLength": 5000 }, "kind": { "type": "string", "enum": [ "banned", "closed" ] }, "reason": { "type": "string", "minLength": 0, "maxLength": 5000 }, "changedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [], "additionalProperties": true } } }, "required": [ "canSend", "restrictions" ], "additionalProperties": true } }, "required": [ "messages", "nextCursor" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "chat:read" ], "x-actor-capability": "member", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false }, "post": { "operationId": "sendConversationMessage", "tags": [ "Chat" ], "summary": "Reply in an organization conversation", "description": "The actor must be a participant or staff with organization chat access. Empty text is only allowed when attachments are present. Public image URLs must pass the existing upload allowlist; document URLs must come from authenticated attachment upload. Never replay your own bot message webhook as a new client message.\n\nActor capability: member. Required token scopes: chat:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "201 {status:'accepted',messageId,message:{id,conversationId,senderId,senderName,body,kind,metadata,createdAt,clientRequestId?}}. Moderation rejection is 422 error.code=CHAT_MESSAGE_BLOCKED and was not delivered. An uncertain commit is 503 error.code=CHAT_DELIVERY_UNCERTAIN: retry with the SAME Idempotency-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "accepted" ] }, "messageId": { "type": "string", "format": "uuid" }, "message": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "conversationId": { "type": "string", "format": "uuid" }, "senderId": { "type": "string", "format": "uuid" }, "senderName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "body": { "type": "string", "minLength": 0, "maxLength": 5000 }, "kind": { "type": "string", "enum": [ "text", "system", "blocked" ] }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Platform scrape metadata. Keep credentials out of this field." }, "deletedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "clientRequestId": { "type": "string", "format": "uuid" } }, "required": [ "id", "conversationId", "senderId", "body", "kind", "createdAt" ], "additionalProperties": true } }, "required": [ "status", "messageId", "message" ], "additionalProperties": false } } } }, "201": { "description": "201 {status:'accepted',messageId,message:{id,conversationId,senderId,senderName,body,kind,metadata,createdAt,clientRequestId?}}. Moderation rejection is 422 error.code=CHAT_MESSAGE_BLOCKED and was not delivered. An uncertain commit is 503 error.code=CHAT_DELIVERY_UNCERTAIN: retry with the SAME Idempotency-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "accepted" ] }, "messageId": { "type": "string", "format": "uuid" }, "message": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "conversationId": { "type": "string", "format": "uuid" }, "senderId": { "type": "string", "format": "uuid" }, "senderName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "body": { "type": "string", "minLength": 0, "maxLength": 5000 }, "kind": { "type": "string", "enum": [ "text", "system", "blocked" ] }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Platform scrape metadata. Keep credentials out of this field." }, "deletedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "clientRequestId": { "type": "string", "format": "uuid" } }, "required": [ "id", "conversationId", "senderId", "body", "kind", "createdAt" ], "additionalProperties": true } }, "required": [ "status", "messageId", "message" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "minLength": 0, "maxLength": 5000 }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2048 }, "mimeType": { "type": "string", "minLength": 1, "maxLength": 128 }, "name": { "type": "string", "minLength": 0, "maxLength": 200 }, "width": { "type": "integer", "minimum": 1, "maximum": 16384 }, "height": { "type": "integer", "minimum": 1, "maximum": 16384 }, "size": { "type": "integer", "minimum": 1, "maximum": 5242880 } }, "required": [ "url", "mimeType" ], "additionalProperties": false }, "maxItems": 10, "minItems": 0 }, "clientRequestId": { "type": "string", "format": "uuid" } }, "required": [ "body" ], "additionalProperties": false } } } }, "x-required-scopes": [ "chat:write" ], "x-actor-capability": "member", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/chat/conversations/{conversationId}/read": { "post": { "operationId": "markConversationRead", "tags": [ "Chat" ], "summary": "Advance the read marker", "description": "Actor capability: member. Required token scopes: chat:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "200 {unreadCount,unreadDelta}. The message must belong to this accessible conversation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "unreadCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "unreadDelta": { "type": "integer" } }, "required": [ "unreadCount", "unreadDelta" ], "additionalProperties": false } } } }, "201": { "description": "200 {unreadCount,unreadDelta}. The message must belong to this accessible conversation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "unreadCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "unreadDelta": { "type": "integer" } }, "required": [ "unreadCount", "unreadDelta" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "messageId": { "type": "string", "format": "uuid" } }, "required": [ "messageId" ], "additionalProperties": false } } } }, "x-required-scopes": [ "chat:write" ], "x-actor-capability": "member", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/chat/conversations/{conversationId}/messages/{messageId}": { "delete": { "operationId": "deleteConversationMessage", "tags": [ "Chat" ], "summary": "Delete your own message", "description": "Actor capability: member. Required token scopes: chat:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "messageId", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "200 {id,conversationId}. Only the original sender can delete; conversation ID must match.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "conversationId": { "type": "string", "format": "uuid" } }, "required": [ "id", "conversationId" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "chat:write" ], "x-actor-capability": "member", "x-risk": "destructive", "x-human-required": false, "x-idempotency-required": true } }, "/chat/unread-count": { "get": { "operationId": "getChatUnreadCount", "tags": [ "Chat" ], "summary": "Read total unread count", "description": "Actor capability: member. Required token scopes: chat:read.", "security": [ { "organizationToken": [] } ], "parameters": [], "responses": { "200": { "description": "{count:number} for the actor's accessible conversations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "count" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "chat:read" ], "x-actor-capability": "member", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/chat/conversations/{conversationId}/profiles": { "get": { "operationId": "getConversationProfiles", "tags": [ "Chat" ], "summary": "Read profiles shared in the conversation", "description": "Actor capability: member. Required token scopes: chat:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Shared profile array. Sensitive credentials and hidden profile-section text are redacted in automation responses by default.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "displayName": { "type": "string", "minLength": 0, "maxLength": 5000 }, "platform": { "type": "string", "minLength": 0, "maxLength": 5000 }, "photoUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "status": { "type": "string", "enum": [ "active", "completed", "cancelled" ] }, "twoFactorKey": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "id", "displayName", "platform", "photoUrl", "status" ], "additionalProperties": true } } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "chat:read" ], "x-actor-capability": "member", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/chat/conversations/{conversationId}/client-recap": { "get": { "operationId": "getClientConversationRecap", "tags": [ "Chat" ], "summary": "Read the client conversation recap", "description": "Actor capability: member. Required token scopes: chat:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Authorized client recap; the existing service role and conversation checks apply.", "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "memberSince": { "type": "string", "format": "date-time" }, "totalRentals": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "activeRentals": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalSpentCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "userId", "name", "memberSince", "totalRentals", "activeRentals", "totalSpentCents" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "chat:read" ], "x-actor-capability": "member", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/chat/conversations/{conversationId}/agent-recap": { "get": { "operationId": "getProviderConversationRecap", "tags": [ "Chat" ], "summary": "Read the provider conversation recap", "description": "Actor capability: member. Required token scopes: chat:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Organization provider recap, rental context and current messaging state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "memberSince": { "type": "string", "format": "date-time" }, "accountsOperated": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "rentedNow": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalEarnedCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "userId", "name", "memberSince", "accountsOperated", "rentedNow", "totalEarnedCents" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "chat:read" ], "x-actor-capability": "member", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/chat/conversations/{conversationId}/hide": { "post": { "operationId": "hideConversation", "tags": [ "Chat" ], "summary": "Hide a conversation for the actor", "description": "Actor capability: member. Required token scopes: chat:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "{success:true}; hides locally for this actor without deleting the customer's history.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "201": { "description": "{success:true}; hides locally for this actor without deleting the customer's history.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "chat:write" ], "x-actor-capability": "member", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/chat/conversations/with-user/{userId}": { "post": { "operationId": "startUserConversation", "tags": [ "Chat" ], "summary": "Find or create a user conversation", "description": "Actor capability: member. Required token scopes: chat:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "{conversationId:string}; external clients require a real prior booking with this organization. Arbitrary unsolicited DMs and customer impersonation are not allowed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversationId": { "type": "string", "format": "uuid" } }, "required": [ "conversationId" ], "additionalProperties": false } } } }, "201": { "description": "{conversationId:string}; external clients require a real prior booking with this organization. Arbitrary unsolicited DMs and customer impersonation are not allowed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversationId": { "type": "string", "format": "uuid" } }, "required": [ "conversationId" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "chat:write" ], "x-actor-capability": "member", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/chat/conversations/team/{userId}": { "post": { "operationId": "startTeamConversation", "tags": [ "Chat" ], "summary": "Find or create a staff conversation", "description": "Actor capability: member. Required token scopes: chat:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "{conversationId:string}; target must satisfy organization/team membership checks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversationId": { "type": "string", "format": "uuid" } }, "required": [ "conversationId" ], "additionalProperties": false } } } }, "201": { "description": "{conversationId:string}; target must satisfy organization/team membership checks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversationId": { "type": "string", "format": "uuid" } }, "required": [ "conversationId" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "chat:write" ], "x-actor-capability": "member", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/chat/conversations/for-booking/{bookingId}": { "post": { "operationId": "getConversationForRental", "tags": [ "Chat" ], "summary": "Find the conversation for a rental", "description": "Actor capability: member. Required token scopes: chat:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "bookingId", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "{conversationId:string}; checks access to the existing rental conversation; does not send a message.", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversationId": { "type": "string", "format": "uuid" } }, "required": [ "conversationId" ], "additionalProperties": false } } } }, "201": { "description": "{conversationId:string}; checks access to the existing rental conversation; does not send a message.", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversationId": { "type": "string", "format": "uuid" } }, "required": [ "conversationId" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "chat:read" ], "x-actor-capability": "member", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/chat/attachments/capabilities": { "get": { "operationId": "getChatAttachmentCapabilities", "tags": [ "Chat attachments" ], "summary": "Read attachment limits and types", "description": "Actor capability: member. Required token scopes: chat:read.", "security": [ { "organizationToken": [] } ], "parameters": [], "responses": { "200": { "description": "Supported attachment capabilities. Documents are limited to 5 MiB and always downloaded as attachments.", "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "boolean" }, "maxFileBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "documents", "maxFileBytes" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "chat:read" ], "x-actor-capability": "member", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/chat/attachments/{conversationId}": { "post": { "operationId": "uploadChatDocument", "tags": [ "Chat attachments" ], "summary": "Upload a conversation document", "description": "Actor capability: member. Required token scopes: chat:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Stored attachment metadata with an authenticated document URL; byte signature, extension and MIME must agree.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 0, "maxLength": 2048 }, "name": { "type": "string", "minLength": 0, "maxLength": 200 }, "mimeType": { "type": "string", "minLength": 0, "maxLength": 128 }, "size": { "type": "integer", "minimum": 1, "maximum": 5242880 } }, "required": [ "url", "name", "mimeType", "size" ], "additionalProperties": true } } } }, "201": { "description": "Stored attachment metadata with an authenticated document URL; byte signature, extension and MIME must agree.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 0, "maxLength": 2048 }, "name": { "type": "string", "minLength": 0, "maxLength": 200 }, "mimeType": { "type": "string", "minLength": 0, "maxLength": 128 }, "size": { "type": "integer", "minimum": 1, "maximum": 5242880 } }, "required": [ "url", "name", "mimeType", "size" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "mimeType": { "type": "string", "enum": [ "application/pdf", "text/plain", "text/csv", "text/markdown", "application/msword", "application/vnd.ms-excel", "application/vnd.ms-powerpoint", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "application/vnd.openxmlformats-officedocument.presentationml.presentation", "application/zip" ] }, "base64": { "type": "string", "minLength": 4, "maxLength": 6990508 } }, "required": [ "name", "mimeType", "base64" ], "additionalProperties": false } } } }, "x-required-scopes": [ "chat:write" ], "x-actor-capability": "member", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/chat/attachments/{conversationId}/{uploaderId}/{fileId}": { "get": { "operationId": "downloadChatDocument", "tags": [ "Chat attachments" ], "summary": "Download an accessible chat document", "description": "Actor capability: member. Required token scopes: chat:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "uploaderId", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "fileId", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Binary application/octet-stream response with Content-Disposition: attachment and private/no-store headers; ordinary API redaction does not touch bytes.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "chat:read" ], "x-actor-capability": "member", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/payments/bookings/{id}/invoices": { "get": { "operationId": "getRentalInvoices", "tags": [ "Rental invoices" ], "summary": "Read rental invoices", "description": "Actor capability: member. Required token scopes: rentals:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Stripe invoices for an authorized rental; tenant-bound provider access is checked before the shared invoice service.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 0, "maxLength": 5000 }, "number": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "status": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "amountPaid": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 0, "maxLength": 5000 }, "periodStart": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "periodEnd": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hostedInvoiceUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "createdAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "billingReason": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "creditAppliedCents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "creditAppliedDays": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "number", "status", "amountPaid", "currency", "periodStart", "periodEnd", "hostedInvoiceUrl", "createdAt", "billingReason", "creditAppliedCents", "creditAppliedDays" ], "additionalProperties": true } } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "rentals:read" ], "x-actor-capability": "member", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/org-payout-connections": { "get": { "operationId": "listPayoutConnections", "tags": [ "Payout connections" ], "summary": "List organization payout sources", "description": "Default 50, maximum 100. Follow nextCursor with the same search, tenant and resource until null. Creation cutoff excludes later inserts; mutable fields may change between pages. Unsupported search returns 400.\n\nActor capability: member. Required token scopes: payouts:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "See list organization payout sources pagination and response notes.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "See list organization payout sources pagination and response notes.", "schema": { "type": "string", "minLength": 1, "maxLength": 768 } }, { "name": "search", "in": "query", "required": false, "description": "See list organization payout sources pagination and response notes.", "schema": { "type": "string", "minLength": 0, "maxLength": 200 } } ], "responses": { "200": { "description": "{data: bounded payout-connections summaries[], nextCursor: string | null}. Fetch detail endpoints for full records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "enum": [ "self_custody", "circle", "bridge" ] }, "label": { "type": [ "string", "null" ] }, "isDefault": { "type": "boolean" }, "enabled": { "type": "boolean" }, "walletAddress": { "type": [ "string", "null" ] }, "walletChain": { "type": [ "string", "null" ] }, "walletCurrency": { "type": [ "string", "null" ] }, "walletProvider": { "type": [ "string", "null" ] }, "circleWalletId": { "type": [ "string", "null" ] }, "createdById": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "provider", "label", "isDefault", "enabled", "walletAddress", "walletChain", "walletCurrency", "walletProvider", "circleWalletId", "createdById", "createdAt", "updatedAt" ], "additionalProperties": false }, "maxItems": 100, "minItems": 0 }, "nextCursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 768 } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "payouts:read" ], "x-actor-capability": "member", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/org-payout-connections/wallet": { "post": { "operationId": "connectPayoutWallet", "tags": [ "Payout connections" ], "summary": "Register a self-custody payout wallet", "description": "Registration does not grant signing control. Actual self-custody transfers require the wallet holder's signature; supported chains are EVM chains, not Tron.\n\nActor capability: manager. Required token scopes: payouts:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Registered wallet connection.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "enum": [ "self_custody", "circle", "bridge" ] }, "label": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "isDefault": { "type": "boolean" }, "enabled": { "type": "boolean" }, "walletAddress": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "walletChain": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "walletCurrency": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "walletProvider": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "circleWalletId": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "simBalanceCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdById": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "provider", "label", "isDefault", "enabled", "walletAddress", "walletChain", "walletCurrency", "walletProvider", "circleWalletId", "simBalanceCents", "createdById", "createdAt", "updatedAt" ], "additionalProperties": true } } } }, "201": { "description": "Registered wallet connection.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "enum": [ "self_custody", "circle", "bridge" ] }, "label": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "isDefault": { "type": "boolean" }, "enabled": { "type": "boolean" }, "walletAddress": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "walletChain": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "walletCurrency": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "walletProvider": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "circleWalletId": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "simBalanceCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdById": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "provider", "label", "isDefault", "enabled", "walletAddress", "walletChain", "walletCurrency", "walletProvider", "circleWalletId", "simBalanceCents", "createdById", "createdAt", "updatedAt" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 0, "maxLength": 60 }, "walletAddress": { "type": "string", "minLength": 8, "maxLength": 120 }, "walletChain": { "type": "string", "enum": [ "base", "polygon", "ethereum", "arbitrum", "optimism" ] }, "walletProvider": { "type": "string", "minLength": 0, "maxLength": 60 } }, "required": [ "walletAddress", "walletChain" ], "additionalProperties": false } } } }, "x-required-scopes": [ "payouts:write" ], "x-actor-capability": "manager", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/org-payout-connections/circle": { "post": { "operationId": "createCirclePayoutWallet", "tags": [ "Payout connections" ], "summary": "Provision an organization Circle wallet", "description": "Actor capability: manager. Required token scopes: payouts:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Created managed wallet connection. Requires configured Circle integration and eligible chain/currency.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "enum": [ "self_custody", "circle", "bridge" ] }, "label": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "isDefault": { "type": "boolean" }, "enabled": { "type": "boolean" }, "walletAddress": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "walletChain": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "walletCurrency": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "walletProvider": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "circleWalletId": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "simBalanceCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdById": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "provider", "label", "isDefault", "enabled", "walletAddress", "walletChain", "walletCurrency", "walletProvider", "circleWalletId", "simBalanceCents", "createdById", "createdAt", "updatedAt" ], "additionalProperties": true } } } }, "201": { "description": "Created managed wallet connection. Requires configured Circle integration and eligible chain/currency.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "enum": [ "self_custody", "circle", "bridge" ] }, "label": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "isDefault": { "type": "boolean" }, "enabled": { "type": "boolean" }, "walletAddress": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "walletChain": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "walletCurrency": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "walletProvider": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "circleWalletId": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "simBalanceCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdById": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "provider", "label", "isDefault", "enabled", "walletAddress", "walletChain", "walletCurrency", "walletProvider", "circleWalletId", "simBalanceCents", "createdById", "createdAt", "updatedAt" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 0, "maxLength": 60 }, "chain": { "type": "string", "enum": [ "base", "polygon", "ethereum", "arbitrum", "optimism" ] }, "currency": { "type": "string", "enum": [ "usdc", "usdt" ] } }, "required": [], "additionalProperties": false } } } }, "x-required-scopes": [ "payouts:write" ], "x-actor-capability": "manager", "x-risk": "external", "x-human-required": false, "x-idempotency-required": true } }, "/org-payout-connections/{id}/balance": { "get": { "operationId": "getPayoutWalletBalance", "tags": [ "Payout connections" ], "summary": "Read a payout wallet balance", "description": "Actor capability: member. Required token scopes: payouts:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current balance and provider state for an organization connection.", "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "string", "minLength": 0, "maxLength": 5000 }, "address": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "chain": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "simulate": { "type": "boolean" }, "availableCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "heldCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "debtCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "nextReleaseAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "amount", "address", "chain", "simulate" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "payouts:read" ], "x-actor-capability": "member", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/org-payout-connections/{id}/withdraw": { "post": { "operationId": "withdrawPayoutWallet", "tags": [ "Payout connections" ], "summary": "Withdraw managed wallet funds", "description": "Owner or canWithdraw grant plus explicit token scope are required. Idempotency-Key is mandatory at the API boundary. Set the provider idempotencyKey consistently when supplied. This moves funds.\n\nActor capability: withdraw. Required token scopes: payouts:withdraw.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Withdrawal transaction state. Amounts use USD cents; external provider validation and balance checks apply.", "content": { "application/json": { "schema": { "type": "object", "properties": { "transferId": { "type": "string", "minLength": 0, "maxLength": 5000 }, "status": { "type": "string", "enum": [ "processing", "paid", "failed" ] } }, "required": [ "transferId", "status" ], "additionalProperties": true } } } }, "201": { "description": "Withdrawal transaction state. Amounts use USD cents; external provider validation and balance checks apply.", "content": { "application/json": { "schema": { "type": "object", "properties": { "transferId": { "type": "string", "minLength": 0, "maxLength": 5000 }, "status": { "type": "string", "enum": [ "processing", "paid", "failed" ] } }, "required": [ "transferId", "status" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "toAddress": { "type": "string", "minLength": 8, "maxLength": 120 }, "amountCents": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "toAddress", "amountCents" ], "additionalProperties": false } } } }, "x-required-scopes": [ "payouts:withdraw" ], "x-actor-capability": "withdraw", "x-risk": "financial", "x-human-required": false, "x-idempotency-required": true } }, "/org-payout-connections/{id}/transactions": { "get": { "operationId": "listPayoutTransactions", "tags": [ "Payout connections" ], "summary": "Read legacy payout transaction history", "description": "limit 1–50. Choose transfers or adjustments and follow the returned cursor. Provider transfers are refreshed by the existing service.\n\nActor capability: member. Required token scopes: payouts:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "source", "in": "query", "required": false, "description": "See read legacy payout transaction history pagination and response notes.", "schema": { "type": "string", "enum": [ "transfers", "adjustments" ], "default": "transfers" } }, { "name": "limit", "in": "query", "required": false, "description": "See read legacy payout transaction history pagination and response notes.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "See read legacy payout transaction history pagination and response notes.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Same bounded transfer/adjustment history as GET /org-payout-connections/:id/history; source defaults to transfers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 0, "maxLength": 5000 }, "type": { "type": "string", "enum": [ "in", "out" ] }, "amount": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "counterparty": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "status": { "type": "string", "enum": [ "processing", "paid", "failed" ] }, "state": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "txHash": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "explorerUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "networkFee": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "date": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "label": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "reason": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "accountName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "clientName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "id", "type", "amount", "counterparty", "status", "state", "txHash", "explorerUrl", "networkFee", "date" ], "additionalProperties": true } }, "cursor": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "hasMore": { "type": "boolean" } }, "required": [ "items", "cursor", "hasMore" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "payouts:read" ], "x-actor-capability": "member", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/org-payout-connections/{id}/history": { "get": { "operationId": "listPayoutHistory", "tags": [ "Payout connections" ], "summary": "Read paginated payout history", "description": "limit 1–50; cursor UUID from the previous response; source is transfers or adjustments.\n\nActor capability: member. Required token scopes: payouts:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "source", "in": "query", "required": false, "description": "See read paginated payout history pagination and response notes.", "schema": { "type": "string", "enum": [ "transfers", "adjustments" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "See read paginated payout history pagination and response notes.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "See read paginated payout history pagination and response notes.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "Cursor history page from the wallet service.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 0, "maxLength": 5000 }, "type": { "type": "string", "enum": [ "in", "out" ] }, "amount": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "counterparty": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "status": { "type": "string", "enum": [ "processing", "paid", "failed" ] }, "state": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "txHash": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "explorerUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "networkFee": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "date": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "label": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "reason": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "accountName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "clientName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "id", "type", "amount", "counterparty", "status", "state", "txHash", "explorerUrl", "networkFee", "date" ], "additionalProperties": true } }, "cursor": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "hasMore": { "type": "boolean" } }, "required": [ "items", "cursor", "hasMore" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "payouts:read" ], "x-actor-capability": "member", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/org-payout-connections/{id}/transactions/{txId}": { "get": { "operationId": "getPayoutTransaction", "tags": [ "Payout connections" ], "summary": "Read a payout transaction", "description": "Actor capability: member. Required token scopes: payouts:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "txId", "in": "path", "required": true, "description": "Provider transaction identifier belonging to this payout source.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "Transaction detail including status and explorer link; txId is a provider transaction identifier.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "processing", "paid", "failed" ] }, "state": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "txHash": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "explorerUrl": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "status", "state", "txHash", "explorerUrl" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "payouts:read" ], "x-actor-capability": "member", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/org-payout-connections/{id}/default": { "patch": { "operationId": "setDefaultPayoutConnection", "tags": [ "Payout connections" ], "summary": "Choose the default payout source", "description": "Actor capability: manager. Required token scopes: payouts:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Updated default connection.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "payouts:write" ], "x-actor-capability": "manager", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/org-payout-connections/{id}": { "delete": { "operationId": "deletePayoutConnection", "tags": [ "Payout connections" ], "summary": "Remove a payout connection", "description": "Actor capability: manager. Required token scopes: payouts:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Connection removal result; this does not erase provider transaction history.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "payouts:write" ], "x-actor-capability": "manager", "x-risk": "destructive", "x-human-required": false, "x-idempotency-required": true } }, "/payroll/month": { "get": { "operationId": "getPayrollMonth", "tags": [ "Payroll" ], "summary": "Read monthly payroll", "description": "Actor capability: manager. Required token scopes: payroll:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "year", "in": "query", "required": true, "description": "See read monthly payroll pagination and response notes.", "schema": { "type": "integer", "minimum": 2000, "maximum": 2200 } }, { "name": "month", "in": "query", "required": true, "description": "See read monthly payroll pagination and response notes.", "schema": { "type": "integer", "minimum": 1, "maximum": 12 } } ], "responses": { "200": { "description": "Agent earnings/payroll for the calendar year and month. Both query parameters are required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "year": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "month": { "type": "integer", "minimum": 1, "maximum": 12 }, "complete": { "type": "boolean" }, "runId": { "type": [ "string", "null" ], "format": "uuid" }, "runStatus": { "type": [ "string", "null" ], "enum": [ "pending", "processing", "completed", null ] }, "totalCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "items": { "type": "array", "items": { "type": "object", "properties": { "agentUserId": { "type": "string", "format": "uuid" }, "agentName": { "type": "string", "minLength": 0, "maxLength": 5000 }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "pending", "processing", "paid", "failed", "skipped" ] }, "failureReason": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "profileId": { "type": "string", "format": "uuid" }, "displayName": { "type": "string", "minLength": 0, "maxLength": 5000 }, "daysRented": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "daysInMonth": { "type": "integer", "minimum": 1, "maximum": 31 }, "commissionCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "rentedSince": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "profileId", "displayName", "daysRented", "daysInMonth", "commissionCents" ], "additionalProperties": true } }, "hasPayoutMethod": { "type": "boolean" }, "payoutMethod": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "external_wallet" ] }, "walletAddress": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "walletChain": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "walletCurrency": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "type", "walletAddress", "walletChain", "walletCurrency" ], "additionalProperties": true } }, "required": [ "agentUserId", "agentName", "amountCents", "status", "failureReason", "breakdown", "hasPayoutMethod", "payoutMethod" ], "additionalProperties": true } } }, "required": [ "year", "month", "complete", "runId", "runStatus", "totalCents", "items" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "payroll:read" ], "x-actor-capability": "manager", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/payroll/month/sync": { "post": { "operationId": "syncPayrollMonth", "tags": [ "Payroll" ], "summary": "Refresh pending monthly payroll", "description": "Actor capability: manager. Required token scopes: payroll:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Provider-refreshed pending payout states; may trigger existing completion notifications.", "content": { "application/json": { "schema": { "type": "object", "properties": { "year": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "month": { "type": "integer", "minimum": 1, "maximum": 12 }, "complete": { "type": "boolean" }, "runId": { "type": [ "string", "null" ], "format": "uuid" }, "runStatus": { "type": [ "string", "null" ], "enum": [ "pending", "processing", "completed", null ] }, "totalCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "items": { "type": "array", "items": { "type": "object", "properties": { "agentUserId": { "type": "string", "format": "uuid" }, "agentName": { "type": "string", "minLength": 0, "maxLength": 5000 }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "pending", "processing", "paid", "failed", "skipped" ] }, "failureReason": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "profileId": { "type": "string", "format": "uuid" }, "displayName": { "type": "string", "minLength": 0, "maxLength": 5000 }, "daysRented": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "daysInMonth": { "type": "integer", "minimum": 1, "maximum": 31 }, "commissionCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "rentedSince": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "profileId", "displayName", "daysRented", "daysInMonth", "commissionCents" ], "additionalProperties": true } }, "hasPayoutMethod": { "type": "boolean" }, "payoutMethod": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "external_wallet" ] }, "walletAddress": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "walletChain": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "walletCurrency": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "type", "walletAddress", "walletChain", "walletCurrency" ], "additionalProperties": true } }, "required": [ "agentUserId", "agentName", "amountCents", "status", "failureReason", "breakdown", "hasPayoutMethod", "payoutMethod" ], "additionalProperties": true } } }, "required": [ "year", "month", "complete", "runId", "runStatus", "totalCents", "items" ], "additionalProperties": true } } } }, "201": { "description": "Provider-refreshed pending payout states; may trigger existing completion notifications.", "content": { "application/json": { "schema": { "type": "object", "properties": { "year": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "month": { "type": "integer", "minimum": 1, "maximum": 12 }, "complete": { "type": "boolean" }, "runId": { "type": [ "string", "null" ], "format": "uuid" }, "runStatus": { "type": [ "string", "null" ], "enum": [ "pending", "processing", "completed", null ] }, "totalCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "items": { "type": "array", "items": { "type": "object", "properties": { "agentUserId": { "type": "string", "format": "uuid" }, "agentName": { "type": "string", "minLength": 0, "maxLength": 5000 }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "pending", "processing", "paid", "failed", "skipped" ] }, "failureReason": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "profileId": { "type": "string", "format": "uuid" }, "displayName": { "type": "string", "minLength": 0, "maxLength": 5000 }, "daysRented": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "daysInMonth": { "type": "integer", "minimum": 1, "maximum": 31 }, "commissionCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "rentedSince": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "profileId", "displayName", "daysRented", "daysInMonth", "commissionCents" ], "additionalProperties": true } }, "hasPayoutMethod": { "type": "boolean" }, "payoutMethod": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "external_wallet" ] }, "walletAddress": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "walletChain": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "walletCurrency": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "type", "walletAddress", "walletChain", "walletCurrency" ], "additionalProperties": true } }, "required": [ "agentUserId", "agentName", "amountCents", "status", "failureReason", "breakdown", "hasPayoutMethod", "payoutMethod" ], "additionalProperties": true } } }, "required": [ "year", "month", "complete", "runId", "runStatus", "totalCents", "items" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "year": { "type": "integer", "minimum": 2000, "maximum": 2200 }, "month": { "type": "integer", "minimum": 1, "maximum": 12 } }, "required": [ "year", "month" ], "additionalProperties": false } } } }, "x-required-scopes": [ "payroll:write" ], "x-actor-capability": "manager", "x-risk": "external", "x-human-required": false, "x-idempotency-required": true } }, "/payroll/pay": { "post": { "operationId": "payMonthlyAgents", "tags": [ "Payroll" ], "summary": "Create or pay monthly payroll", "description": "This action can move funds. Requires owner or canPayAgents grant and explicit token scope.\n\nActor capability: payAgents. Required token scopes: payroll:pay.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Payroll result/run; auto executes provider payment when configured; manual records off-platform handling.", "content": { "application/json": { "schema": { "type": "object", "properties": { "year": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "month": { "type": "integer", "minimum": 1, "maximum": 12 }, "complete": { "type": "boolean" }, "runId": { "type": [ "string", "null" ], "format": "uuid" }, "runStatus": { "type": [ "string", "null" ], "enum": [ "pending", "processing", "completed", null ] }, "totalCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "items": { "type": "array", "items": { "type": "object", "properties": { "agentUserId": { "type": "string", "format": "uuid" }, "agentName": { "type": "string", "minLength": 0, "maxLength": 5000 }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "pending", "processing", "paid", "failed", "skipped" ] }, "failureReason": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "profileId": { "type": "string", "format": "uuid" }, "displayName": { "type": "string", "minLength": 0, "maxLength": 5000 }, "daysRented": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "daysInMonth": { "type": "integer", "minimum": 1, "maximum": 31 }, "commissionCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "rentedSince": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "profileId", "displayName", "daysRented", "daysInMonth", "commissionCents" ], "additionalProperties": true } }, "hasPayoutMethod": { "type": "boolean" }, "payoutMethod": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "external_wallet" ] }, "walletAddress": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "walletChain": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "walletCurrency": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "type", "walletAddress", "walletChain", "walletCurrency" ], "additionalProperties": true } }, "required": [ "agentUserId", "agentName", "amountCents", "status", "failureReason", "breakdown", "hasPayoutMethod", "payoutMethod" ], "additionalProperties": true } } }, "required": [ "year", "month", "complete", "runId", "runStatus", "totalCents", "items" ], "additionalProperties": true } } } }, "201": { "description": "Payroll result/run; auto executes provider payment when configured; manual records off-platform handling.", "content": { "application/json": { "schema": { "type": "object", "properties": { "year": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "month": { "type": "integer", "minimum": 1, "maximum": 12 }, "complete": { "type": "boolean" }, "runId": { "type": [ "string", "null" ], "format": "uuid" }, "runStatus": { "type": [ "string", "null" ], "enum": [ "pending", "processing", "completed", null ] }, "totalCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "items": { "type": "array", "items": { "type": "object", "properties": { "agentUserId": { "type": "string", "format": "uuid" }, "agentName": { "type": "string", "minLength": 0, "maxLength": 5000 }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "pending", "processing", "paid", "failed", "skipped" ] }, "failureReason": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "profileId": { "type": "string", "format": "uuid" }, "displayName": { "type": "string", "minLength": 0, "maxLength": 5000 }, "daysRented": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "daysInMonth": { "type": "integer", "minimum": 1, "maximum": 31 }, "commissionCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "rentedSince": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "profileId", "displayName", "daysRented", "daysInMonth", "commissionCents" ], "additionalProperties": true } }, "hasPayoutMethod": { "type": "boolean" }, "payoutMethod": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "external_wallet" ] }, "walletAddress": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "walletChain": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "walletCurrency": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "type", "walletAddress", "walletChain", "walletCurrency" ], "additionalProperties": true } }, "required": [ "agentUserId", "agentName", "amountCents", "status", "failureReason", "breakdown", "hasPayoutMethod", "payoutMethod" ], "additionalProperties": true } } }, "required": [ "year", "month", "complete", "runId", "runStatus", "totalCents", "items" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "year": { "type": "integer", "minimum": 2000, "maximum": 2200 }, "month": { "type": "integer", "minimum": 1, "maximum": 12 }, "agentUserIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 1000, "minItems": 0 }, "mode": { "type": "string", "enum": [ "auto", "manual" ] } }, "required": [ "year", "month", "agentUserIds", "mode" ], "additionalProperties": false } } } }, "x-required-scopes": [ "payroll:pay" ], "x-actor-capability": "payAgents", "x-risk": "financial", "x-human-required": false, "x-idempotency-required": true } }, "/payroll/runs": { "get": { "operationId": "listPayrollRuns", "tags": [ "Payroll" ], "summary": "List payroll runs", "description": "Default 50, maximum 100. Follow nextCursor with the same search, tenant and resource until null. Creation cutoff excludes later inserts; mutable fields may change between pages. Unsupported search returns 400.\n\nActor capability: manager. Required token scopes: payroll:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "See list payroll runs pagination and response notes.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "See list payroll runs pagination and response notes.", "schema": { "type": "string", "minLength": 1, "maxLength": 768 } }, { "name": "search", "in": "query", "required": false, "description": "See list payroll runs pagination and response notes.", "schema": { "type": "string", "minLength": 0, "maxLength": 200 } } ], "responses": { "200": { "description": "{data: bounded payroll-runs summaries[], nextCursor: string | null}. Fetch detail endpoints for full records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "periodYear": { "type": "integer" }, "periodMonth": { "type": "integer", "minimum": 1, "maximum": 12 }, "status": { "type": "string", "enum": [ "pending", "processing", "completed" ] }, "totalCents": { "type": "integer" }, "createdById": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "organizationId", "periodYear", "periodMonth", "status", "totalCents", "createdById", "createdAt", "completedAt" ], "additionalProperties": false }, "maxItems": 100, "minItems": 0 }, "nextCursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 768 } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "payroll:read" ], "x-actor-capability": "manager", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/payroll/runs/{id}": { "get": { "operationId": "getPayrollRun", "tags": [ "Payroll" ], "summary": "Read a payroll run", "description": "Actor capability: manager. Required token scopes: payroll:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Run with payment items and states.", "content": { "application/json": { "schema": { "type": "object", "properties": { "run": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "periodYear": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "periodMonth": { "type": "integer", "minimum": 1, "maximum": 12 }, "status": { "type": "string", "enum": [ "pending", "processing", "completed" ] }, "totalCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdById": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "organizationId", "periodYear", "periodMonth", "status", "totalCents", "createdById", "createdAt", "completedAt" ], "additionalProperties": true }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agentUserId": { "type": "string", "format": "uuid" }, "agentName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "agentEmail": { "type": "string", "minLength": 0, "maxLength": 5000 }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "pending", "processing", "paid", "failed", "skipped" ] }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "profileId": { "type": "string", "format": "uuid" }, "displayName": { "type": "string", "minLength": 0, "maxLength": 5000 }, "daysRented": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "daysInMonth": { "type": "integer", "minimum": 1, "maximum": 31 }, "commissionCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "rentedSince": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "profileId", "displayName", "daysRented", "daysInMonth", "commissionCents" ], "additionalProperties": true } }, "bridgeTransferId": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "failureReason": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "paidAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "agentUserId", "agentName", "agentEmail", "amountCents", "status", "breakdown", "bridgeTransferId", "failureReason", "paidAt" ], "additionalProperties": true } } }, "required": [ "run", "items" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "payroll:read" ], "x-actor-capability": "manager", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/payroll/runs/{id}/execute": { "post": { "operationId": "executePayrollRun", "tags": [ "Payroll" ], "summary": "Execute payroll items", "description": "Actor capability: payAgents. Required token scopes: payroll:pay.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Execution result. Omitting itemIds asks the existing service to execute eligible items; supply explicit IDs for deliberate selection.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "completed", "processing" ] } }, "required": [ "status" ], "additionalProperties": true } } } }, "201": { "description": "Execution result. Omitting itemIds asks the existing service to execute eligible items; supply explicit IDs for deliberate selection.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "completed", "processing" ] } }, "required": [ "status" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "itemIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 1000, "minItems": 0 } }, "required": [], "additionalProperties": false } } } }, "x-required-scopes": [ "payroll:pay" ], "x-actor-capability": "payAgents", "x-risk": "financial", "x-human-required": false, "x-idempotency-required": true } }, "/payroll/runs/{id}/mark-paid": { "post": { "operationId": "markPayrollItemsPaid", "tags": [ "Payroll" ], "summary": "Record off-platform payroll payment", "description": "Actor capability: payAgents. Required token scopes: payroll:pay.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Updated payment records; does not prove an external payment occurred.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "completed", "processing" ] } }, "required": [ "status" ], "additionalProperties": true } } } }, "201": { "description": "Updated payment records; does not prove an external payment occurred.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "completed", "processing" ] } }, "required": [ "status" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "itemIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 1000, "minItems": 0 } }, "required": [ "itemIds" ], "additionalProperties": false } } } }, "x-required-scopes": [ "payroll:pay" ], "x-actor-capability": "payAgents", "x-risk": "financial", "x-human-required": false, "x-idempotency-required": true } }, "/payouts": { "get": { "operationId": "listAgentPayouts", "tags": [ "Payroll" ], "summary": "Read the agent payout ledger", "description": "Default 50, maximum 100. Follow nextCursor with the same search, tenant and resource until null. Creation cutoff excludes later inserts; mutable fields may change between pages. Unsupported search returns 400.\n\nActor capability: member. Required token scopes: payroll:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "See read the agent payout ledger pagination and response notes.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "See read the agent payout ledger pagination and response notes.", "schema": { "type": "string", "minLength": 1, "maxLength": 768 } }, { "name": "search", "in": "query", "required": false, "description": "See read the agent payout ledger pagination and response notes.", "schema": { "type": "string", "minLength": 0, "maxLength": 200 } } ], "responses": { "200": { "description": "{data: bounded payouts summaries[], nextCursor: string | null}. Fetch detail endpoints for full records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agentUserId": { "type": "string", "format": "uuid" }, "agentName": { "type": [ "string", "null" ] }, "agentEmail": { "type": "string" }, "bookingId": { "type": [ "string", "null" ], "format": "uuid" }, "amountCents": { "type": "integer" }, "currency": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "paid", "failed", "cancelled" ] }, "transferId": { "type": [ "string", "null" ] }, "failureReason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "paidAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "agentUserId", "agentName", "agentEmail", "bookingId", "amountCents", "currency", "status", "transferId", "failureReason", "createdAt", "paidAt" ], "additionalProperties": false }, "maxItems": 100, "minItems": 0 }, "nextCursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 768 } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "payroll:read" ], "x-actor-capability": "member", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/payouts/{id}/pay": { "post": { "operationId": "executeAgentPayout", "tags": [ "Payroll" ], "summary": "Pay one agent payout", "description": "Actor capability: payAgents. Required token scopes: payroll:pay.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Payout execution result; existing durable payroll/payment checks still apply.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "minLength": 0, "maxLength": 5000 }, "transferId": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "status" ], "additionalProperties": true } } } }, "201": { "description": "Payout execution result; existing durable payroll/payment checks still apply.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "minLength": 0, "maxLength": 5000 }, "transferId": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "status" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "payroll:pay" ], "x-actor-capability": "payAgents", "x-risk": "financial", "x-human-required": false, "x-idempotency-required": true } }, "/payments/connect/onboard": { "post": { "operationId": "startStripeOnboarding", "tags": [ "Stripe Connect" ], "summary": "Start Stripe Connect onboarding", "description": "Actor capability: owner. Required token scopes: payouts:write.\n\nA human must complete the hosted verification/signing flow; an API response does not complete that interaction.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "{accountId:string}. Creates or reuses the organization's Stripe account. A human completes identity/business verification through the embedded account session; this call does not return an onboarding URL or complete verification.", "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "accountId" ], "additionalProperties": true } } } }, "201": { "description": "{accountId:string}. Creates or reuses the organization's Stripe account. A human completes identity/business verification through the embedded account session; this call does not return an onboarding URL or complete verification.", "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "accountId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "businessName": { "type": "string", "minLength": 2, "maxLength": 200 }, "country": { "type": "string", "minLength": 2, "maxLength": 2 } }, "required": [ "businessName" ], "additionalProperties": false } } } }, "x-required-scopes": [ "payouts:write" ], "x-actor-capability": "owner", "x-risk": "external", "x-human-required": true, "x-idempotency-required": true } }, "/payments/connect/status": { "get": { "operationId": "getStripeConnectStatus", "tags": [ "Stripe Connect" ], "summary": "Read Stripe Connect readiness", "description": "Actor capability: owner. Required token scopes: payouts:read.", "security": [ { "organizationToken": [] } ], "parameters": [], "responses": { "200": { "description": "Connection/verification/charges/payout readiness state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": [ "string", "null" ], "enum": [ "pending", "active", "restricted", "disconnected", null ] }, "accountId": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "earnings": { "type": [ "object", "null" ], "properties": { "available": { "type": "integer" }, "pending": { "type": "integer" }, "refundedTotalCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "recentPayouts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 0, "maxLength": 5000 }, "amount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "minLength": 0, "maxLength": 5000 }, "arrivalDate": { "type": "string", "format": "date-time" }, "failureCode": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "failureMessage": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "id", "amount", "status", "arrivalDate", "failureCode", "failureMessage" ], "additionalProperties": true } }, "recentRefunds": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 0, "maxLength": 5000 }, "amount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 0, "maxLength": 5000 }, "status": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "reason": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "createdAt": { "type": "string", "format": "date-time" }, "chargeId": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "id", "amount", "currency", "status", "reason", "createdAt", "chargeId" ], "additionalProperties": true } } }, "required": [ "available", "pending", "refundedTotalCents", "recentPayouts", "recentRefunds" ], "additionalProperties": true }, "bankAccount": { "type": [ "object", "null" ], "properties": { "bankName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "last4": { "type": "string", "minLength": 0, "maxLength": 5000 }, "currency": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "bankName", "last4", "currency" ], "additionalProperties": true }, "accountName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "requirements": { "type": [ "object", "null" ], "properties": { "fields": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "currentDeadline": { "type": [ "string", "null" ], "format": "date-time" }, "disabledReason": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 0, "maxLength": 5000 }, "reason": { "type": "string", "minLength": 0, "maxLength": 5000 }, "requirement": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "code", "reason", "requirement" ], "additionalProperties": true } }, "pastDue": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "pendingVerification": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "futureFields": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "futureDeadline": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "fields", "currentDeadline", "disabledReason", "errors", "pastDue", "pendingVerification", "futureFields", "futureDeadline" ], "additionalProperties": true }, "chargesEnabled": { "type": "boolean" }, "payoutsEnabled": { "type": "boolean" }, "detailsSubmitted": { "type": "boolean" }, "pendingReview": { "type": "boolean" } }, "required": [ "status", "accountId", "earnings", "bankAccount", "accountName", "requirements", "chargesEnabled", "payoutsEnabled", "detailsSubmitted", "pendingReview" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "payouts:read" ], "x-actor-capability": "owner", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/payments/connect/account-session": { "post": { "operationId": "createStripeAccountSession", "tags": [ "Stripe Connect" ], "summary": "Create an embedded Stripe account session", "description": "Actor capability: owner. Required token scopes: payouts:write.\n\nA human must complete the hosted verification/signing flow; an API response does not complete that interaction.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Ephemeral account session for the authenticated owner's interactive Stripe settings. Treat the returned client secret as sensitive; never put it in bot logs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "clientSecret": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "clientSecret" ], "additionalProperties": true } } } }, "201": { "description": "Ephemeral account session for the authenticated owner's interactive Stripe settings. Treat the returned client secret as sensitive; never put it in bot logs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "clientSecret": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "clientSecret" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "payouts:write" ], "x-actor-capability": "owner", "x-risk": "write", "x-human-required": true, "x-idempotency-required": true } }, "/payments/connect/payout": { "post": { "operationId": "createStripePayout", "tags": [ "Stripe Connect" ], "summary": "Request a Stripe payout", "description": "Actor capability: owner. Required token scopes: payouts:withdraw.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Stripe payout result from available balance. This moves funds and requires explicit withdrawal scope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 0, "maxLength": 5000 }, "amount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "arrivalDate": { "type": "string", "format": "date-time" } }, "required": [ "id", "amount", "arrivalDate" ], "additionalProperties": true } } } }, "201": { "description": "Stripe payout result from available balance. This moves funds and requires explicit withdrawal scope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 0, "maxLength": 5000 }, "amount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "arrivalDate": { "type": "string", "format": "date-time" } }, "required": [ "id", "amount", "arrivalDate" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "payouts:withdraw" ], "x-actor-capability": "owner", "x-risk": "financial", "x-human-required": false, "x-idempotency-required": true } }, "/payments/connect/transactions": { "get": { "operationId": "listStripeTransactions", "tags": [ "Stripe Connect" ], "summary": "Read Stripe Connect transactions", "description": "limit 1–100; cursor is the provider startingAfter identifier, not a UUID.\n\nActor capability: owner. Required token scopes: payouts:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "See read stripe connect transactions pagination and response notes.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "See read stripe connect transactions pagination and response notes.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "Stripe transaction page.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 0, "maxLength": 5000 }, "type": { "type": "string", "minLength": 0, "maxLength": 5000 }, "createdAt": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "amount": { "type": "integer" }, "fee": { "type": "integer" }, "net": { "type": "integer" }, "currency": { "type": "string", "minLength": 0, "maxLength": 5000 }, "status": { "type": "string", "minLength": 0, "maxLength": 5000 }, "sourceId": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "id", "type", "createdAt", "description", "amount", "fee", "net", "currency", "status", "sourceId" ], "additionalProperties": true } }, "hasMore": { "type": "boolean" }, "cursor": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "items", "hasMore", "cursor" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "payouts:read" ], "x-actor-capability": "owner", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/payments/connect/disconnect": { "post": { "operationId": "disconnectStripeConnect", "tags": [ "Stripe Connect" ], "summary": "Disconnect Stripe Connect", "description": "Actor capability: owner. Required token scopes: payouts:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Disconnection result. May stop receiving organization payouts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": true } } } }, "201": { "description": "Disconnection result. May stop receiving organization payouts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "payouts:write" ], "x-actor-capability": "owner", "x-risk": "destructive", "x-human-required": false, "x-idempotency-required": true } }, "/payments/connect/reset": { "post": { "operationId": "resetStripeConnect", "tags": [ "Stripe Connect" ], "summary": "Reset Stripe Connect setup", "description": "Actor capability: owner. Required token scopes: payouts:write.\n\nA human must complete the hosted verification/signing flow; an API response does not complete that interaction.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Reset connection setup; a human may need to complete onboarding again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": true } } } }, "201": { "description": "Reset connection setup; a human may need to complete onboarding again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "payouts:write" ], "x-actor-capability": "owner", "x-risk": "destructive", "x-human-required": true, "x-idempotency-required": true } }, "/developer/webhooks": { "get": { "operationId": "listWebhooks", "tags": [ "Webhooks" ], "summary": "List webhook destinations", "description": "Actor capability: owner. Required token scopes: webhooks:read.", "security": [ { "organizationToken": [] } ], "parameters": [], "responses": { "200": { "description": "{data:Endpoint[],eventTypes:string[],workerEnabled:boolean}. Up to ten endpoints per organization. Endpoint={id,name,url,events,enabled,disabledReason,createdAt,updatedAt}; no secret is returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 0, "maxLength": 80 }, "url": { "type": "string", "minLength": 0, "maxLength": 2048 }, "events": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "enabled": { "type": "boolean" }, "disabledReason": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "url", "events", "enabled" ], "additionalProperties": true }, "maxItems": 10 }, "eventTypes": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "workerEnabled": { "type": "boolean" } }, "required": [ "data", "eventTypes", "workerEnabled" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "webhooks:read" ], "x-actor-capability": "owner", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false }, "post": { "operationId": "createWebhook", "tags": [ "Webhooks" ], "summary": "Create a webhook destination", "description": "The events array must contain distinct supported event types. HTTPS/public-address validation runs before saving. Delivery requires the worker and encryption configuration.\n\nActor capability: owner. Required token scopes: webhooks:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Endpoint plus signingSecret, shown once. Keep the signing secret in your bot's secret store; it is not an API token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 0, "maxLength": 80 }, "url": { "type": "string", "minLength": 0, "maxLength": 2048 }, "events": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "enabled": { "type": "boolean" }, "disabledReason": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "signingSecret": { "type": "string", "minLength": 0, "maxLength": 100 } }, "required": [ "id", "signingSecret" ], "additionalProperties": true } } } }, "201": { "description": "Endpoint plus signingSecret, shown once. Keep the signing secret in your bot's secret store; it is not an API token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 0, "maxLength": 80 }, "url": { "type": "string", "minLength": 0, "maxLength": 2048 }, "events": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "enabled": { "type": "boolean" }, "disabledReason": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "signingSecret": { "type": "string", "minLength": 0, "maxLength": 100 } }, "required": [ "id", "signingSecret" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "url": { "type": "string", "minLength": 1, "maxLength": 2048, "format": "uri", "description": "Public HTTPS destination on port 443. Private/reserved addresses and redirects are rejected; server rechecks DNS at delivery." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "profile.created", "profile.updated", "profile.deleted", "rental.created", "rental.updated", "rental.deleted", "chat.message.created", "chat.message.deleted", "webhook.test" ] }, "maxItems": 9, "minItems": 1, "uniqueItems": true } }, "required": [ "name", "url", "events" ], "additionalProperties": false } } } }, "x-required-scopes": [ "webhooks:write" ], "x-actor-capability": "owner", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true } }, "/developer/webhooks/{id}": { "patch": { "operationId": "updateWebhook", "tags": [ "Webhooks" ], "summary": "Edit or disable a webhook", "description": "Actor capability: owner. Required token scopes: webhooks:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "Updated endpoint; disabling stops new deliveries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 0, "maxLength": 80 }, "url": { "type": "string", "minLength": 0, "maxLength": 2048 }, "events": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "enabled": { "type": "boolean" }, "disabledReason": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "url", "events", "enabled" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "url": { "type": "string", "minLength": 1, "maxLength": 2048, "format": "uri", "description": "Public HTTPS destination on port 443. Private/reserved addresses and redirects are rejected; server rechecks DNS at delivery." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "profile.created", "profile.updated", "profile.deleted", "rental.created", "rental.updated", "rental.deleted", "chat.message.created", "chat.message.deleted", "webhook.test" ] }, "maxItems": 9, "minItems": 1, "uniqueItems": true }, "enabled": { "type": "boolean" } }, "required": [], "additionalProperties": false } } } }, "x-required-scopes": [ "webhooks:write" ], "x-actor-capability": "owner", "x-risk": "write", "x-human-required": false, "x-idempotency-required": true }, "delete": { "operationId": "deleteWebhook", "tags": [ "Webhooks" ], "summary": "Delete a webhook destination", "description": "Actor capability: owner. Required token scopes: webhooks:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "{deleted:true,id}. Removes destination and stops delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" } }, "required": [ "deleted", "id" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "webhooks:write" ], "x-actor-capability": "owner", "x-risk": "destructive", "x-human-required": false, "x-idempotency-required": true } }, "/developer/webhooks/{id}/test": { "post": { "operationId": "testWebhook", "tags": [ "Webhooks" ], "summary": "Queue a test webhook", "description": "Actor capability: owner. Required token scopes: webhooks:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "{eventId,deliveryId,status:'queued'}. A queue result is not proof of remote receipt; check delivery status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "eventId": { "type": "string", "format": "uuid" }, "deliveryId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued" ] } }, "required": [ "eventId", "deliveryId", "status" ], "additionalProperties": false } } } }, "201": { "description": "{eventId,deliveryId,status:'queued'}. A queue result is not proof of remote receipt; check delivery status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "eventId": { "type": "string", "format": "uuid" }, "deliveryId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued" ] } }, "required": [ "eventId", "deliveryId", "status" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "webhooks:write" ], "x-actor-capability": "owner", "x-risk": "external", "x-human-required": false, "x-idempotency-required": true } }, "/developer/webhooks/{id}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "tags": [ "Webhooks" ], "summary": "Read webhook delivery attempts", "description": "limit 1–100, default 50; cursor is an opaque decimal string. Keep lastCursor even when hasMore=false to resume later.\n\nActor capability: owner. Required token scopes: webhooks:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "See read webhook delivery attempts pagination and response notes.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque decimal sequence cursor from this feed's prior response. Send as a string.", "schema": { "type": "string", "minLength": 1, "maxLength": 19, "pattern": "^[0-9]+$", "description": "Opaque decimal sequence cursor from this feed's prior response. Send as a string." } } ], "responses": { "200": { "description": "{data:[{cursor,id,eventId,status,attempts,replayCount,nextAttemptAt,lastStatus,lastError,deliveredAt,createdAt}],nextCursor,lastCursor,hasMore}.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "cursor": { "type": "string", "minLength": 0, "maxLength": 5000 }, "id": { "type": "string", "format": "uuid" }, "eventId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "in_flight", "delivered", "dead" ] }, "attempts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "replayCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "nextAttemptAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastStatus": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "lastError": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "cursor", "id", "eventId", "status", "attempts", "replayCount" ], "additionalProperties": true } }, "nextCursor": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "lastCursor": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "hasMore": { "type": "boolean" } }, "required": [ "data", "nextCursor", "lastCursor", "hasMore" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "webhooks:read" ], "x-actor-capability": "owner", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/developer/webhooks/{id}/deliveries/{deliveryId}/replay": { "post": { "operationId": "replayWebhookDelivery", "tags": [ "Webhooks" ], "summary": "Replay a completed or failed delivery", "description": "Actor capability: owner. Required token scopes: webhooks:write.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "deliveryId", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique stable key for this intended action. Retry the exact same method/path/body with the same key. Reuse with a different payload returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "growthbot-create-profile-01" } } ], "responses": { "200": { "description": "{id,eventId,status:'queued'}. Only dead or delivered attempts can be replayed; recipients must deduplicate by event ID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "eventId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued" ] } }, "required": [ "id", "eventId", "status" ], "additionalProperties": false } } } }, "201": { "description": "{id,eventId,status:'queued'}. Only dead or delivered attempts can be replayed; recipients must deduplicate by event ID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "eventId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued" ] } }, "required": [ "id", "eventId", "status" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "webhooks:write" ], "x-actor-capability": "owner", "x-risk": "external", "x-human-required": false, "x-idempotency-required": true } }, "/developer/events": { "get": { "operationId": "listOrganizationEvents", "tags": [ "Events" ], "summary": "Resume the organization event feed", "description": "Fetch resource context with a separately scoped API call. Events are durable and webhook delivery is at least once; duplicate and out-of-order deliveries are possible.\n\nlimit 1–100, default 50; cursor is an opaque decimal string. Persist lastCursor after each successful poll. Optional type narrows the feed.\n\nActor capability: owner. Required token scopes: events:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "See resume the organization event feed pagination and response notes.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque decimal sequence cursor from this feed's prior response. Send as a string.", "schema": { "type": "string", "minLength": 1, "maxLength": 19, "pattern": "^[0-9]+$", "description": "Opaque decimal sequence cursor from this feed's prior response. Send as a string." } }, { "name": "type", "in": "query", "required": false, "description": "See resume the organization event feed pagination and response notes.", "schema": { "type": "string", "enum": [ "profile.created", "profile.updated", "profile.deleted", "rental.created", "rental.updated", "rental.deleted", "chat.message.created", "chat.message.deleted", "webhook.test" ] } } ], "responses": { "200": { "description": "{data:[{cursor,id,type,data,timestamp}],nextCursor,lastCursor,hasMore}. Event data is thin resource identifiers with no message body, credential or hidden text.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "cursor": { "type": "string", "minLength": 0, "maxLength": 5000 }, "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "profile.created", "profile.updated", "profile.deleted" ] }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "profileId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "available", "rented", "unlisted" ] }, "platform": { "type": "string", "enum": [ "linkedin", "facebook", "x", "upwork", "reddit" ] } }, "required": [ "profileId", "status", "platform" ], "additionalProperties": false } }, "required": [ "cursor", "id", "type", "timestamp", "data" ], "additionalProperties": true }, { "type": "object", "properties": { "cursor": { "type": "string", "minLength": 0, "maxLength": 5000 }, "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "rental.created", "rental.updated", "rental.deleted" ] }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "rentalId": { "type": "string", "format": "uuid" }, "profileId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "active", "completed", "cancelled" ] }, "paymentStatus": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 } }, "required": [ "rentalId", "profileId", "status", "paymentStatus" ], "additionalProperties": false } }, "required": [ "cursor", "id", "type", "timestamp", "data" ], "additionalProperties": true }, { "type": "object", "properties": { "cursor": { "type": "string", "minLength": 0, "maxLength": 5000 }, "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "chat.message.created", "chat.message.deleted" ] }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "messageId": { "type": "string", "format": "uuid" }, "conversationId": { "type": "string", "format": "uuid" }, "senderId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "text", "system" ] } }, "required": [ "messageId", "conversationId", "senderId", "kind" ], "additionalProperties": false } }, "required": [ "cursor", "id", "type", "timestamp", "data" ], "additionalProperties": true }, { "type": "object", "properties": { "cursor": { "type": "string", "minLength": 0, "maxLength": 5000 }, "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "webhook.test" ] }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "endpointId": { "type": "string", "format": "uuid" } }, "required": [ "endpointId" ], "additionalProperties": false } }, "required": [ "cursor", "id", "type", "timestamp", "data" ], "additionalProperties": true } ] } }, "nextCursor": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "lastCursor": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 5000 }, "hasMore": { "type": "boolean" }, "retentionDays": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "retainedSince": { "type": "string", "format": "date-time" }, "prunedThroughCursor": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [ "data", "nextCursor", "lastCursor", "hasMore", "retentionDays", "retainedSince", "prunedThroughCursor" ], "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "events:read" ], "x-actor-capability": "owner", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/developer/capabilities": { "get": { "operationId": "getApiCapabilities", "tags": [ "Developer tools" ], "summary": "Read the deployed API capabilities", "description": "Actor capability: owner. Required token scopes: organization:read.", "security": [ { "organizationToken": [] } ], "parameters": [], "responses": { "200": { "description": "{enabled:boolean,financialActionsEnabled:boolean,version:string,actorId:string,organizationId:string,scopes:string[],operations:[{id,method,path,scopes,capability}]}. Catalog of enabled actions and issuing actor/organization identity; financial write actions and scopes are absent unless separately enabled. Each call still checks the token's granted scopes and actor permissions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "financialActionsEnabled": { "type": "boolean" }, "version": { "type": "string", "minLength": 0, "maxLength": 5000 }, "actorId": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "scopes": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "operations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 0, "maxLength": 5000 }, "method": { "type": "string", "minLength": 0, "maxLength": 5000 }, "path": { "type": "string", "minLength": 0, "maxLength": 5000 }, "scopes": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "capability": { "type": "string", "minLength": 0, "maxLength": 5000 }, "deprecated": { "type": "boolean" }, "replacementOperationId": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [], "additionalProperties": false } } }, "required": [ "enabled", "financialActionsEnabled", "version", "actorId", "organizationId", "scopes", "operations" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "organization:read" ], "x-actor-capability": "owner", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/developer/openapi.json": { "get": { "operationId": "getOpenApiContract", "tags": [ "Developer tools" ], "summary": "Download the current OpenAPI contract", "description": "Actor capability: member. Required token scopes: organization:read.", "security": [ { "organizationToken": [] } ], "parameters": [], "responses": { "200": { "description": "OpenAPI 3.1 document generated from this exact route allowlist. This is the contract for the deployed API version.", "content": { "application/json": { "schema": { "type": "object", "properties": { "openapi": { "type": "string", "minLength": 0, "maxLength": 5000 }, "info": { "type": "object", "properties": { "title": { "type": "string", "minLength": 0, "maxLength": 5000 }, "version": { "type": "string", "minLength": 0, "maxLength": 5000 }, "description": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [], "additionalProperties": false }, "servers": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 0, "maxLength": 5000 }, "description": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [], "additionalProperties": false } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 0, "maxLength": 5000 } }, "required": [], "additionalProperties": false } }, "paths": { "type": "object", "additionalProperties": true, "description": "Platform scrape metadata. Keep credentials out of this field." }, "components": { "type": "object", "additionalProperties": true, "description": "Platform scrape metadata. Keep credentials out of this field." } }, "required": [ "openapi", "info", "servers", "paths", "components" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "organization:read" ], "x-actor-capability": "member", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/developer/operations": { "get": { "operationId": "listApiExecutions", "tags": [ "Developer tools" ], "summary": "Read organization API execution history", "description": "Actor capability: owner. Required token scopes: organization:read.", "security": [ { "organizationToken": [] } ], "parameters": [], "responses": { "200": { "description": "Array of the latest 100 executions: {id,operation,state,statusCode,createdAt,finishedAt}. Bodies, tokens and signing secrets are excluded; state is executing/completed/uncertain. No pagination query is supported by this legacy journal view.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "operation": { "type": "string", "minLength": 0, "maxLength": 5000 }, "state": { "type": "string", "enum": [ "executing", "completed", "uncertain" ] }, "statusCode": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "operation", "state", "createdAt" ], "additionalProperties": false } } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "organization:read" ], "x-actor-capability": "owner", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } }, "/developer/operations/{id}": { "get": { "operationId": "getApiExecution", "tags": [ "Developer tools" ], "summary": "Read one organization API execution", "description": "Actor capability: owner. Required token scopes: organization:read.", "security": [ { "organizationToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource UUID scoped to the current organization.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "One execution receipt with id,operation,state,statusCode,createdAt,finishedAt. It remains discoverable after newer writes push it beyond the recent history view. Bodies and secrets are excluded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "operation": { "type": "string", "minLength": 0, "maxLength": 5000 }, "state": { "type": "string", "enum": [ "executing", "completed", "uncertain" ] }, "statusCode": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "operation", "state", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Token scope or actor capability denied, disabled/banned account, or action unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "API rate/concurrency limit exceeded; use backoff and Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-required-scopes": [ "organization:read" ], "x-actor-capability": "owner", "x-risk": "read", "x-human-required": false, "x-idempotency-required": false } } }, "components": { "securitySchemes": { "organizationToken": { "type": "http", "scheme": "bearer", "bearerFormat": "Organization API token", "description": "Create a scoped token in Organization settings > Developers. A token is bound to one organization and its issuing actor; JWT session credentials are not bot tokens." } }, "schemas": { "ApiError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 0, "maxLength": 100 }, "message": { "type": [ "string", "array" ], "description": "Safe human-readable error; validation can produce a string array." }, "requestId": { "type": "string", "minLength": 0, "maxLength": 100 }, "retryable": { "type": "boolean" }, "details": { "type": "object", "additionalProperties": true, "description": "Platform scrape metadata. Keep credentials out of this field." }, "persistedId": { "type": "string", "format": "uuid" } }, "required": [ "code", "message", "requestId", "retryable" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }