{"openapi":"3.1.0","info":{"title":"Blackpearl Platform API","description":"The public developer API for PearlEngine-powered GTM data and intelligence. Authenticate with a project-scoped API key: `Authorization: Bearer bp_live_…`.","version":"0.2.0","x-api-version":"v1","x-stability":"ga"},"paths":{"/v1/connectors":{"get":{"tags":["Connectors"],"summary":"Connector Catalog List","operationId":"connector_catalog_list_v1_connectors_get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorCatalogResponse"},"example":{"catalog_version":"Example catalog version","connectors":[{"manifest_version":"Example manifest version","key":"Example key","name":"Example name","category":"Example category","declared_integration_kinds":["rest"],"availability":"catalog_only","verification_mode":"unavailable","homepage_url":"https://example.com","docs_url":"https://example.com","key_acquisition_url":"https://example.com","capabilities":["Example capabilities"],"credential_fields":[{"key":"Example key","label":"Example label","description":"Example description","environment_aliases":["Example environment aliases"],"required":true,"secret":true}],"provenance":{"repository":"Example repository","commit":"Example commit","source_paths":["Example source paths"]}}]}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"Connector Catalog List. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."}},"/v1/connections":{"get":{"tags":["Connectors"],"summary":"Connection List","operationId":"connection_list_v1_connections_get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicConnectionsResponse"},"example":{"connections":[{"id":"Example id","project_id":"Example project id","provider_key":"Example provider key","manifest_version":"Example manifest version","name":"Example name","configured_fields":["Example configured fields"],"credentials_version":0,"status":"configured","verification":{"mode":"unavailable","status":"unavailable","network_request_made":false},"created_at":"Example created at","updated_at":"Example updated at"}]}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"Connection List. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."}},"/v1/capabilities":{"get":{"tags":["Capabilities"],"summary":"List enabled capabilities","description":"List the public capabilities enabled for the API key's organization. Use `key` values when interpreting usage rollups and capability-specific workflows.","operationId":"capabilities_v1_capabilities_get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Enabled capabilities for the authenticated organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCapabilitiesResponse"},"example":{"capabilities":[{"key":"playbooks","name":"Playbooks","category":"Generation","status":"ga","description":"Generate AI sales playbooks for a target account.","docs_slug":"playbooks","enabled":true}]}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga"}},"/v1/playbook-templates":{"get":{"tags":["Playbooks"],"summary":"List stage-aware Playbook templates","description":"Return the versioned curated template catalog. Optionally filter by one shared deal stage before binding a template to a Playbooks request.","operationId":"list_playbook_templates_v1_playbook_templates_get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"stage","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stage"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicPlaybookTemplateCatalog"},"example":{"catalog_version":"Example catalog version","stages":["Example stages"],"templates":[{"key":"Example key","name":"Example name","stage":"Example stage","focus":"Example focus","guidance":["Example guidance"]}]}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga"}},"/v1/playbooks":{"post":{"tags":["Playbooks"],"summary":"Create a Playbooks job","description":"Validate a target company, enqueue a Playbooks generation job, and return its typed job response. Poll `GET /v1/jobs/{job_id}` until it reaches a terminal state. Send `Idempotency-Key` so an ambiguous request can safely replay its original response for 24 hours.","operationId":"create_playbook_v1_playbooks_post","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":255},{"type":"null"}],"description":"Deduplicates this job-creation operation within the authenticated project for 24 hours.","title":"Idempotency-Key"},"description":"Deduplicates this job-creation operation within the authenticated project for 24 hours."},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaybookInput"},"example":{"target_company_domain":"acme.example","anchor_company":"Northstar Analytics","product_info":"Revenue-intelligence software for enterprise sales teams.","tone":"consultative","sections":["summary","value_props","personas","objections"],"model":"default"}}}},"responses":{"202":{"description":"Accepted Playbooks job. The typed result is null until the job succeeds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicPlaybookJobResponse"},"example":{"id":"job_playbook_123","type":"playbooks","status":"succeeded","progress":100,"project_id":"proj_123","input":{"target_company_domain":"acme.example","anchor_company":"Northstar Analytics","tone":"consultative","model":"default"},"result":{"company_name":"Acme Corporation","domain":"acme.example","website":"https://acme.example","industry":"Software","business_summary":"Acme sells revenue-intelligence software to enterprise teams.","business_objective":"Improve enterprise pipeline conversion.","value_props":["Increase forecast confidence."],"sales_angles":["Connect scattered revenue data."],"key_personas":[{"name":"Alex Morgan","title":"VP Revenue Operations","description":"Owns revenue-process efficiency and forecasting.","tags":["economic_buyer"],"conversation_starters":["Ask about forecast accuracy."]}],"key_services":["Revenue analytics"],"relevant_tech_stack":[{"name":"Salesforce","logo":"https://assets.example/salesforce.svg"}],"tech_integration_title":"Salesforce integration","tech_integration_examples":["Enrich opportunity review workflows."],"tech_integration_questions":["Which Salesforce objects drive forecasting?"],"potential_objections":[{"objection":"Implementation will take too long.","response":"Start with the existing Salesforce workflow and a focused pilot."}],"meeting_note_example":"Hi Alex, teams like yours use this to remove forecast blind spots.","product_name":"Northstar Analytics","readiness_level":"active_evaluation","contact_overview":"Alex is the recommended first contact.","contact_intelligence":[{"name":"Alex Morgan","title":"VP Revenue Operations","role":"Champion","company":"Acme Corporation","linkedin_url":"https://www.linkedin.com/in/alex-morgan","summary":"Owns the workflow this product improves.","signals":["Hiring for RevOps"]}],"company_context":{"market_position":"Enterprise revenue-intelligence provider","business_model":"B2B SaaS","headquarters":"San Francisco, CA","employee_count":"501-1000","recent_news":["Expanded enterprise sales team."],"competitors":["Contoso"]},"intent_analysis":{"intent_score":"high","summary":"Signals suggest an active evaluation.","signals":["Hiring for RevOps"],"topics":["Revenue operations"]},"conversation_strategy":{"opening":"Lead with forecast-quality improvements.","approach":"Connect operational pain to the existing planning cycle.","key_questions":["Where do forecast handoffs break down today?"]},"risks_and_challenges":{"potential_blockers":["Budget timing"],"risks":["Competing internal initiative"],"mitigations":["Offer a focused pilot with measurable outcomes."]}},"usage":{"tokens":4200,"input_tokens":3500,"cached_input_tokens":1200,"cache_write_tokens":300,"output_tokens":700,"reasoning_tokens":180,"cost_usd":0.0123,"backend_requests":1,"backend_runtime_ms":1830},"created_at":"2026-07-13T12:00:00Z","expires_at":"2026-08-12T12:00:00Z","started_at":"2026-07-13T12:00:00Z","finished_at":"2026-07-13T12:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga"}},"/v1/prospects":{"post":{"tags":["Prospecting"],"summary":"Create a Prospecting job","description":"Discover and qualify evidence-backed prospects for an audience specification. Poll `GET /v1/jobs/{job_id}` until the job reaches a terminal state.","operationId":"create_prospecting_job_v1_prospects_post","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":255},{"type":"null"}],"description":"Deduplicates this job-creation operation within the authenticated project for 24 hours.","title":"Idempotency-Key"},"description":"Deduplicates this job-creation operation within the authenticated project for 24 hours."},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectingInput"},"example":{"campaign_name":"Example campaign name","product_info":"Example product info","objective":"Example objective"}}}},"responses":{"202":{"description":"Accepted Prospecting job. The typed result is null until the job succeeds.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PublicPlaybookJobResponse"},{"$ref":"#/components/schemas/PublicAudienceJobResponse"},{"$ref":"#/components/schemas/PublicBrandJobResponse"},{"$ref":"#/components/schemas/ProspectingJobResponse"},{"$ref":"#/components/schemas/MessageTemplateJobResponse"},{"$ref":"#/components/schemas/DocumentJobResponse"}],"discriminator":{"propertyName":"type","mapping":{"playbooks":"#/components/schemas/PublicPlaybookJobResponse","audiences":"#/components/schemas/PublicAudienceJobResponse","brands":"#/components/schemas/PublicBrandJobResponse","prospecting":"#/components/schemas/ProspectingJobResponse","message_templates":"#/components/schemas/MessageTemplateJobResponse","documents":"#/components/schemas/DocumentJobResponse"}},"title":"Response Create Prospecting Job V1 Prospects Post"},"example":{"id":"job_playbook_123","type":"playbooks","status":"succeeded","progress":100,"project_id":"proj_123","input":{"target_company_domain":"acme.example","anchor_company":"Northstar Analytics","tone":"consultative","model":"default"},"result":{"company_name":"Acme Corporation","domain":"acme.example","website":"https://acme.example","industry":"Software","business_summary":"Acme sells revenue-intelligence software to enterprise teams.","business_objective":"Improve enterprise pipeline conversion.","value_props":["Increase forecast confidence."],"sales_angles":["Connect scattered revenue data."],"key_personas":[{"name":"Alex Morgan","title":"VP Revenue Operations","description":"Owns revenue-process efficiency and forecasting.","tags":["economic_buyer"],"conversation_starters":["Ask about forecast accuracy."]}],"key_services":["Revenue analytics"],"relevant_tech_stack":[{"name":"Salesforce","logo":"https://assets.example/salesforce.svg"}],"tech_integration_title":"Salesforce integration","tech_integration_examples":["Enrich opportunity review workflows."],"tech_integration_questions":["Which Salesforce objects drive forecasting?"],"potential_objections":[{"objection":"Implementation will take too long.","response":"Start with the existing Salesforce workflow and a focused pilot."}],"meeting_note_example":"Hi Alex, teams like yours use this to remove forecast blind spots.","product_name":"Northstar Analytics","readiness_level":"active_evaluation","contact_overview":"Alex is the recommended first contact.","contact_intelligence":[{"name":"Alex Morgan","title":"VP Revenue Operations","role":"Champion","company":"Acme Corporation","linkedin_url":"https://www.linkedin.com/in/alex-morgan","summary":"Owns the workflow this product improves.","signals":["Hiring for RevOps"]}],"company_context":{"market_position":"Enterprise revenue-intelligence provider","business_model":"B2B SaaS","headquarters":"San Francisco, CA","employee_count":"501-1000","recent_news":["Expanded enterprise sales team."],"competitors":["Contoso"]},"intent_analysis":{"intent_score":"high","summary":"Signals suggest an active evaluation.","signals":["Hiring for RevOps"],"topics":["Revenue operations"]},"conversation_strategy":{"opening":"Lead with forecast-quality improvements.","approach":"Connect operational pain to the existing planning cycle.","key_questions":["Where do forecast handoffs break down today?"]},"risks_and_challenges":{"potential_blockers":["Budget timing"],"risks":["Competing internal initiative"],"mitigations":["Offer a focused pilot with measurable outcomes."]}},"usage":{"tokens":4200,"input_tokens":3500,"cached_input_tokens":1200,"cache_write_tokens":300,"output_tokens":700,"reasoning_tokens":180,"cost_usd":0.0123,"backend_requests":1,"backend_runtime_ms":1830},"created_at":"2026-07-13T12:00:00Z","expires_at":"2026-08-12T12:00:00Z","started_at":"2026-07-13T12:00:00Z","finished_at":"2026-07-13T12:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga"}},"/v1/prospects/{job_id}/events":{"get":{"tags":["Prospecting"],"summary":"Stream a prospecting run's live thread","description":"Poll the append-only event log of an agentic prospecting run (agent status, streamed messages, discovered leads). Pass the returned `next_after_seq` back as `after_seq` to fetch only newer events.","operationId":"prospecting_run_events_v1_prospects__job_id__events_get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"after_seq","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"After Seq"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":500,"title":"Limit"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"The run's current typed state plus events newer than after_seq.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicProspectingRunEvents"},"example":{"job":{"id":"job_prospecting_123","type":"prospecting","status":"running","progress":55,"project_id":"proj_123","usage":{"cost_usd":0.0},"stages":[{"key":"understand","label":"Understanding the brief","status":"completed"},{"key":"search","label":"Searching the web","status":"running"}],"created_at":"2026-07-13T12:00:00Z","expires_at":"2026-08-12T12:00:00Z","input":{"campaign_name":"North America RevOps leaders","product_info":"Revenue analytics for B2B SaaS.","objective":"Find VP Revenue Operations leaders at mid-market B2B SaaS companies."}},"events":[{"seq":6,"type":"task_status","data":{"label":"Searching the web"},"created_at":"2026-07-13T12:00:00Z"},{"seq":7,"type":"text","data":{"text":"Scanning sources for B2B SaaS accounts hiring RevOps leaders..."},"created_at":"2026-07-13T12:00:00Z"}],"next_after_seq":7}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga"}},"/v1/documents":{"post":{"tags":["Documents"],"summary":"Create a Documents job","description":"Generate finished sales-collateral files — proposals, playbooks, decks, GTM strategies, reports or one-pagers as `.pptx`/`.docx`/`.pdf` — from a `brief`, driven by the Doc Maker managed agent. The platform composes the selling context from your Brand Pack (the organization's default brand unless `brand` selects another profile; the brand must have a completed guideline or the request fails with `409 brand_guideline_missing`) plus the optional `offer`, and the agent follows up to three reference `template_urls`. Poll `GET /v1/jobs/{job_id}` until the job reaches a terminal state, then download each referenced file with `GET /v1/documents/{job_id}/files/{file_id}`. Send `Idempotency-Key` so an ambiguous request can safely replay its original response for 24 hours.","operationId":"create_document_job_v1_documents_post","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":255},{"type":"null"}],"description":"Deduplicates this job-creation operation within the authenticated project for 24 hours.","title":"Idempotency-Key"},"description":"Deduplicates this job-creation operation within the authenticated project for 24 hours."},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentInput"},"example":{"brief":"A first-meeting sales proposal for Acme Corporation's RevOps team: lead with their pipeline-visibility pains, map our onboarding time-to-value, and close with a 90-day rollout plan and pricing summary.","document_type":"proposal","format":"docx","target_domain":"acme.example","brand":"northstar","offer":"analytics_suite","template_urls":["https://cdn.example/templates/enterprise-proposal.docx"],"title":"Acme Corporation proposal","external_ref":"crm-account-123"}}}},"responses":{"202":{"description":"Accepted Documents job. The typed result is null until the job succeeds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentJobResponse"},"example":{"id":"job_document_123","type":"documents","status":"succeeded","progress":100,"project_id":"proj_123","input":{"brief":"A first-meeting sales proposal for Acme Corporation's RevOps team: lead with their pipeline-visibility pains, map our onboarding time-to-value, and close with a 90-day rollout plan and pricing summary.","document_type":"proposal","format":"docx","target_domain":"acme.example","brand":"northstar","offer":"analytics_suite","template_urls":["https://cdn.example/templates/enterprise-proposal.docx"],"title":"Acme Corporation proposal","external_ref":"crm-account-123"},"result":{"schema_version":"2026-07-17","title":"Acme Corporation proposal","request_echo":"A first-meeting sales proposal for Acme Corporation's RevOps team: lead with their pipeline-visibility pains, map our onboarding time-to-value, and close with a 90-day rollout plan and pricing summary.","document_type":"proposal","format":"docx","target_domain":"acme.example","brand":{"profile_id":"brand_01h8z3m2q7","name":"Northstar Analytics","key":"northstar"},"offer":{"offer_id":"offer_01h8z3m2q7","name":"Analytics Suite","key":"analytics_suite"},"files":[{"file_id":"docfile_01h8z3m2q7","filename":"acme-corporation-proposal.docx","format":"docx","size_bytes":48213,"download_path":"/api/orgs/org_123/projects/proj_123/documents/job_document_123/files/docfile_01h8z3m2q7"}],"progress":["Session started — analyzing the request...","Searching: acme.example brand colors","Executing document generation code...","Writing: acme-corporation-proposal.docx"],"model":"claude-sonnet-4-6","duration_seconds":184.2,"external_ref":"crm-account-123","provenance":{"backend":"anthropic.doc_maker","provider":"anthropic"}},"usage":{"tokens":152400,"input_tokens":3500,"cached_input_tokens":1200,"cache_write_tokens":300,"output_tokens":700,"reasoning_tokens":180,"cost_usd":0.8412,"backend_requests":1,"backend_runtime_ms":1830},"stages":[{"key":"prepare","label":"Preparing brand pack & offer","status":"completed"},{"key":"generate","label":"Creating the document","status":"completed"},{"key":"deliver","label":"Delivering files","status":"completed"}],"created_at":"2026-07-13T12:00:00Z","expires_at":"2026-08-12T12:00:00Z","started_at":"2026-07-13T12:00:00Z","finished_at":"2026-07-13T12:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga"}},"/v1/documents/{job_id}/files/{file_id}":{"get":{"tags":["Documents"],"summary":"Download a document file","description":"Download the raw bytes of one collateral file produced by a succeeded Documents job. File identifiers, filenames, formats and sizes are listed in the job result's `files` array. The response body is the file itself with a format-specific `Content-Type` (PPTX, DOCX or PDF) and a `Content-Disposition: attachment` filename; unknown formats stream as `application/octet-stream`. Files share the job's 30-day retention window.","operationId":"download_document_job_file_v1_documents__job_id__files__file_id__get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"file_id","in":"path","required":true,"schema":{"type":"string","title":"File Id"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"The raw file bytes with a format-specific content type and an attachment filename.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"},"example":"Binary document bytes"}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Content-Disposition":{"description":"Attachment disposition containing the sanitized output filename.","schema":{"type":"string","examples":["attachment; filename=\"acme-proposal.docx\""]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga"}},"/v1/account-research":{"post":{"tags":["API"],"summary":"Research an account","description":"Fetch one structured website-intelligence record for a company domain — identity, scale, market, digital presence, buying signals and any surfaced contacts. Synchronous: the record returns in the response. Each successful lookup meters one `prospect_research` request. Unknown domains return `404 account_not_found` unmetered — or set `analyze: true` to fetch and analyze the website on demand (one extra metered request). Set `include_similar: true` to add up to 10 lookalike companies from the similarity index.","operationId":"public_account_research_v1_account_research_post","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAccountResearchIn"},"example":{"analyze":true,"domain":"hubspot.com","include_similar":true}}}},"responses":{"200":{"description":"The structured research record for the requested domain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountResearchResult"},"example":{"schema_version":"2026-07-17","domain":"hubspot.com","retrieved_at":"2026-07-17T12:00:00Z","identity":{"name":"HubSpot","domain":"hubspot.com","url":"https://hubspot.com","summary":"HubSpot is an AI-powered customer platform...","industry":"Software","founding_year":"2006","founders":["Brian Halligan","Dharmesh Shah"],"values":["innovation","customer success"],"adjectives":["AI-powered","integrated"]},"scale":{"employees":4000,"offices":10,"users_mentioned":248000,"primary_country":"US"},"market":{"b2b":true,"b2c":false,"target_customer":"Businesses looking for integrated marketing, sales and service.","target_customer_industries":["Technology","Marketing"],"products":[{"name":"Marketing Hub","description":"Marketing automation platform."}]},"digital":{"about_url":"https://www.hubspot.com/our-story","third_party_integrations":["Zapier","Salesforce"],"api_availability":true,"offers_free_trial":true},"signals":{"ai_ml_initiatives":true,"awards_listed":true,"has_us_presence":true},"contacts":[],"similar_companies":[{"domain":"salesloft.com","name":"Salesloft","summary":"Sales engagement platform for revenue teams.","industry":"Software","country":"US","score":0.49}],"analyzed":false,"provenance":{"backend":"bebop.data","provider":"bebop"}}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga"}},"/v1/campaigns":{"post":{"tags":["Campaigns"],"summary":"Create an Audience campaign","description":"Save a typed Audience targeting specification for repeated cycles without immediately running it. Start a cycle with `POST /v1/campaigns/{campaign_id}/cycles`.","operationId":"create_campaign_v1_campaigns_post","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCampaignCreate"},"example":{"name":"North America RevOps leaders","objective":"Find VP and director-level revenue operations leaders at B2B SaaS companies.","website_url":"northstar.example","product_name":"Northstar Analytics","product_description":"Revenue-intelligence software for enterprise sales teams.","target_size":100,"max_contacts_per_company":3,"excluded_domains":["existing-customer.example"],"playbooks_enabled":false,"model":"default"}}}},"responses":{"200":{"description":"Created or idempotently returned Audience campaign.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCampaign"},"example":{"id":"camp_123","project_id":"proj_123","name":"North America RevOps leaders","input":{"objective":"Find VP Revenue Operations leaders at B2B SaaS companies.","target_size":100,"max_contacts_per_company":3,"model":"default"},"setup_ready":true,"cycle_count":2,"last_cycle_id":"job_audience_123","last_cycle_status":"succeeded","last_cycle_at":"2026-07-13T12:00:00Z","total_cost_usd":1.243,"schedule":{"enabled":true,"interval_hours":168,"dedupe":true,"next_run_at":"2026-07-13T12:00:00Z"},"archived":false,"created_at":"2026-07-13T12:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga"},"get":{"tags":["Campaigns"],"summary":"List Audience campaigns","description":"List non-archived Audience campaigns in the API key's project, newest first. Pass `next_cursor` back as `cursor` to read the next page.","operationId":"list_campaigns_v1_campaigns_get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Cursor page of Audience campaigns.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCampaignsResponse"},"example":{"campaigns":[{"id":"camp_123","project_id":"proj_123","name":"North America RevOps leaders","input":{"objective":"Find VP Revenue Operations leaders at B2B SaaS companies.","target_size":100,"max_contacts_per_company":3,"model":"default"},"setup_ready":true,"cycle_count":2,"last_cycle_id":"job_audience_123","last_cycle_status":"succeeded","last_cycle_at":"2026-07-13T12:00:00Z","total_cost_usd":1.243,"schedule":{"enabled":true,"interval_hours":168,"dedupe":true,"next_run_at":"2026-07-13T12:00:00Z"},"archived":false,"created_at":"2026-07-13T12:00:00Z"}],"next_cursor":"50","total":101}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga"}},"/v1/campaigns/{campaign_id}":{"get":{"tags":["Campaigns"],"summary":"Retrieve an Audience campaign","description":"Return one typed Audience campaign when it belongs to the API key's project.","operationId":"get_campaign_v1_campaigns__campaign_id__get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","title":"Campaign Id"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Audience campaign in the authenticated project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCampaign"},"example":{"id":"camp_123","project_id":"proj_123","name":"North America RevOps leaders","input":{"objective":"Find VP Revenue Operations leaders at B2B SaaS companies.","target_size":100,"max_contacts_per_company":3,"model":"default"},"setup_ready":true,"cycle_count":2,"last_cycle_id":"job_audience_123","last_cycle_status":"succeeded","last_cycle_at":"2026-07-13T12:00:00Z","total_cost_usd":1.243,"schedule":{"enabled":true,"interval_hours":168,"dedupe":true,"next_run_at":"2026-07-13T12:00:00Z"},"archived":false,"created_at":"2026-07-13T12:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga"},"patch":{"tags":["Campaigns"],"summary":"Update a campaign's GTM relations","description":"Update the organizing GTM half of a campaign: name, key, objective, status, metadata, and the brand/offer/playbook/message-template/document relations it sells with. Send an empty string for a relation field to clear it; omit a field to leave it unchanged. This does not run a cycle.","operationId":"update_campaign_v1_campaigns__campaign_id__patch","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","title":"Campaign Id"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCampaignUpdate"},"example":{}}}},"responses":{"200":{"description":"The updated campaign.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCampaign"},"example":{"id":"camp_123","project_id":"proj_123","name":"North America RevOps leaders","input":{"objective":"Find VP Revenue Operations leaders at B2B SaaS companies.","target_size":100,"max_contacts_per_company":3,"model":"default"},"setup_ready":true,"cycle_count":2,"last_cycle_id":"job_audience_123","last_cycle_status":"succeeded","last_cycle_at":"2026-07-13T12:00:00Z","total_cost_usd":1.243,"schedule":{"enabled":true,"interval_hours":168,"dedupe":true,"next_run_at":"2026-07-13T12:00:00Z"},"archived":false,"created_at":"2026-07-13T12:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga"}},"/v1/campaigns/{campaign_id}/cycles":{"post":{"tags":["Campaigns"],"summary":"Create an Audience campaign cycle","description":"Start one asynchronous Audience cycle for a saved campaign. Reusing `Idempotency-Key` with matching input within 24 hours returns the original cycle job rather than creating a duplicate.","operationId":"run_campaign_cycle_v1_campaigns__campaign_id__cycles_post","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","title":"Campaign Id"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":255},{"type":"null"}],"description":"Deduplicates this job-creation operation within the authenticated project for 24 hours.","title":"Idempotency-Key"},"description":"Deduplicates this job-creation operation within the authenticated project for 24 hours."},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"202":{"description":"Accepted Audience cycle job.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAudienceJobResponse"},"example":{"id":"job_audience_123","type":"audiences","status":"succeeded","progress":100,"project_id":"proj_123","campaign_id":"camp_123","input":{"objective":"Find VP Revenue Operations leaders at B2B SaaS companies.","target_size":100,"max_contacts_per_company":3,"model":"default"},"result":{"count":100,"result_shape":"company","generated_at":"2026-07-13T12:00:00Z","rtsa_cycle_id":"cycle_123","contacts_count":230,"avg_final_score":84.2,"max_final_score":96.0,"top_industries":[{"industry":"Software","count":64}],"icp":{"offer":"Northstar Analytics","description":"Enterprise B2B SaaS companies with complex revenue operations.","intent_topics":["revenue operations"],"industries":["Software"],"job_titles":["VP Revenue Operations"]}},"usage":{"tokens":4200,"input_tokens":3500,"cached_input_tokens":1200,"cache_write_tokens":300,"output_tokens":700,"reasoning_tokens":180,"cost_usd":0.0123,"backend_requests":1,"backend_runtime_ms":1830,"candidates":100},"stages":[{"key":"icp","label":"Ideal customer profile","status":"completed"}],"created_at":"2026-07-13T12:00:00Z","expires_at":"2026-08-12T12:00:00Z","started_at":"2026-07-13T12:00:00Z","finished_at":"2026-07-13T12:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga"},"get":{"tags":["Campaigns"],"summary":"List Audience campaign cycles","description":"List the most recent asynchronous Audience cycles for a campaign in descending creation order.","operationId":"list_campaign_cycles_v1_campaigns__campaign_id__cycles_get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","title":"Campaign Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Typed Audience cycle jobs for the campaign.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicAudienceJobResponse"},"title":"Response List Campaign Cycles V1 Campaigns  Campaign Id  Cycles Get"},"example":[{"id":"job_audience_123","type":"audiences","status":"succeeded","progress":100,"project_id":"proj_123","campaign_id":"camp_123","input":{"objective":"Find VP Revenue Operations leaders at B2B SaaS companies.","target_size":100,"max_contacts_per_company":3,"model":"default"},"result":{"count":100,"result_shape":"company","generated_at":"2026-07-13T12:00:00Z","rtsa_cycle_id":"cycle_123","contacts_count":230,"avg_final_score":84.2,"max_final_score":96.0,"top_industries":[{"industry":"Software","count":64}],"icp":{"offer":"Northstar Analytics","description":"Enterprise B2B SaaS companies with complex revenue operations.","intent_topics":["revenue operations"],"industries":["Software"],"job_titles":["VP Revenue Operations"]}},"usage":{"tokens":4200,"input_tokens":3500,"cached_input_tokens":1200,"cache_write_tokens":300,"output_tokens":700,"reasoning_tokens":180,"cost_usd":0.0123,"backend_requests":1,"backend_runtime_ms":1830,"candidates":100},"stages":[{"key":"icp","label":"Ideal customer profile","status":"completed"}],"created_at":"2026-07-13T12:00:00Z","expires_at":"2026-08-12T12:00:00Z","started_at":"2026-07-13T12:00:00Z","finished_at":"2026-07-13T12:00:00Z"}]}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga"}},"/v1/audiences":{"post":{"tags":["Audiences"],"summary":"Create and run an Audience","description":"Create a campaign and start its first asynchronous Audience cycle in one request. Use `Idempotency-Key` when retrying an ambiguous accepted request; matching retries replay the original response for 24 hours.","operationId":"create_audience_v1_audiences_post","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":255},{"type":"null"}],"description":"Deduplicates this job-creation operation within the authenticated project for 24 hours.","title":"Idempotency-Key"},"description":"Deduplicates this job-creation operation within the authenticated project for 24 hours."},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AudienceInput"},"example":{"name":"North America RevOps leaders","objective":"Find VP and director-level revenue operations leaders at B2B SaaS companies.","website_url":"northstar.example","product_name":"Northstar Analytics","product_description":"Revenue-intelligence software for enterprise sales teams.","target_size":100,"max_contacts_per_company":3,"excluded_domains":["existing-customer.example"],"playbooks_enabled":false,"model":"default"}}}},"responses":{"202":{"description":"Accepted Audience job.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAudienceJobResponse"},"example":{"id":"job_audience_123","type":"audiences","status":"succeeded","progress":100,"project_id":"proj_123","campaign_id":"camp_123","input":{"objective":"Find VP Revenue Operations leaders at B2B SaaS companies.","target_size":100,"max_contacts_per_company":3,"model":"default"},"result":{"count":100,"result_shape":"company","generated_at":"2026-07-13T12:00:00Z","rtsa_cycle_id":"cycle_123","contacts_count":230,"avg_final_score":84.2,"max_final_score":96.0,"top_industries":[{"industry":"Software","count":64}],"icp":{"offer":"Northstar Analytics","description":"Enterprise B2B SaaS companies with complex revenue operations.","intent_topics":["revenue operations"],"industries":["Software"],"job_titles":["VP Revenue Operations"]}},"usage":{"tokens":4200,"input_tokens":3500,"cached_input_tokens":1200,"cache_write_tokens":300,"output_tokens":700,"reasoning_tokens":180,"cost_usd":0.0123,"backend_requests":1,"backend_runtime_ms":1830,"candidates":100},"stages":[{"key":"icp","label":"Ideal customer profile","status":"completed"}],"created_at":"2026-07-13T12:00:00Z","expires_at":"2026-08-12T12:00:00Z","started_at":"2026-07-13T12:00:00Z","finished_at":"2026-07-13T12:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga"}},"/v1/audiences/{job_id}/candidates":{"get":{"tags":["Audiences"],"summary":"List Audience candidates","description":"Read a cursor page of typed candidates for a completed Audience job. The job result is a compact summary; use this endpoint for candidate records.","operationId":"list_audience_candidates_v1_audiences__job_id__candidates_get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Q"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","default":"final_score","title":"Sort"}},{"name":"direction","in":"query","required":false,"schema":{"type":"string","default":"desc","title":"Direction"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Cursor page of company or contact candidates.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCandidatesPage"},"example":{"job_id":"job_audience_123","campaign_id":"camp_123","count":100,"total":100,"candidates":[{"result_shape":"company","company_name":"Acme Corporation","company_domain":"acme.example","company_description":"Enterprise B2B SaaS company.","employee_count":"501-1000","primary_industry":"Software","city":"Austin","state":"TX","country":"United States","intent_topics_matched":["revenue operations"],"prelim_score":88.0,"deep_match_score":90.0,"final_score":91.5,"company_score":91.0,"readiness_score":87.0,"contact_score":92.0,"reason":"Strong ICP and intent match.","contact_strategy":"Lead with the primary contact.","contacts":[{"contact_id":5012,"full_name":"Jordan Reyes","job_title":"VP Revenue Operations","business_email":"jordan.reyes@acme.example","linkedin_url":"https://www.linkedin.com/in/jordan-reyes","city":"Austin","state":"TX","country":"United States","final_score":91.5,"validity_score":95.0,"reliability_score":90.0,"fit_score":92.0,"reason":"Owns the workflow the offer improves.","is_primary":true}]}],"next_cursor":"50"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga"}},"/v1/jobs/{job_id}":{"get":{"tags":["Jobs"],"summary":"Retrieve an asynchronous job","description":"Retrieve a job in the API key's project. The `type` discriminator selects the matching Playbooks or Audiences input and result shape.","operationId":"get_job_v1_jobs__job_id__get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Typed Playbooks or Audiences job response.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PublicPlaybookJobResponse"},{"$ref":"#/components/schemas/PublicAudienceJobResponse"},{"$ref":"#/components/schemas/PublicBrandJobResponse"},{"$ref":"#/components/schemas/ProspectingJobResponse"},{"$ref":"#/components/schemas/MessageTemplateJobResponse"},{"$ref":"#/components/schemas/DocumentJobResponse"}],"discriminator":{"propertyName":"type","mapping":{"playbooks":"#/components/schemas/PublicPlaybookJobResponse","audiences":"#/components/schemas/PublicAudienceJobResponse","brands":"#/components/schemas/PublicBrandJobResponse","prospecting":"#/components/schemas/ProspectingJobResponse","message_templates":"#/components/schemas/MessageTemplateJobResponse","documents":"#/components/schemas/DocumentJobResponse"}},"title":"Response Get Job V1 Jobs  Job Id  Get"},"examples":{"playbooks":{"summary":"Completed Playbooks job","value":{"id":"job_playbook_123","type":"playbooks","status":"succeeded","progress":100,"project_id":"proj_123","input":{"target_company_domain":"acme.example","anchor_company":"Northstar Analytics","tone":"consultative","model":"default"},"result":{"company_name":"Acme Corporation","domain":"acme.example","website":"https://acme.example","industry":"Software","business_summary":"Acme sells revenue-intelligence software to enterprise teams.","business_objective":"Improve enterprise pipeline conversion.","value_props":["Increase forecast confidence."],"sales_angles":["Connect scattered revenue data."],"key_personas":[{"name":"Alex Morgan","title":"VP Revenue Operations","description":"Owns revenue-process efficiency and forecasting.","tags":["economic_buyer"],"conversation_starters":["Ask about forecast accuracy."]}],"key_services":["Revenue analytics"],"relevant_tech_stack":[{"name":"Salesforce","logo":"https://assets.example/salesforce.svg"}],"tech_integration_title":"Salesforce integration","tech_integration_examples":["Enrich opportunity review workflows."],"tech_integration_questions":["Which Salesforce objects drive forecasting?"],"potential_objections":[{"objection":"Implementation will take too long.","response":"Start with the existing Salesforce workflow and a focused pilot."}],"meeting_note_example":"Hi Alex, teams like yours use this to remove forecast blind spots.","product_name":"Northstar Analytics","readiness_level":"active_evaluation","contact_overview":"Alex is the recommended first contact.","contact_intelligence":[{"name":"Alex Morgan","title":"VP Revenue Operations","role":"Champion","company":"Acme Corporation","linkedin_url":"https://www.linkedin.com/in/alex-morgan","summary":"Owns the workflow this product improves.","signals":["Hiring for RevOps"]}],"company_context":{"market_position":"Enterprise revenue-intelligence provider","business_model":"B2B SaaS","headquarters":"San Francisco, CA","employee_count":"501-1000","recent_news":["Expanded enterprise sales team."],"competitors":["Contoso"]},"intent_analysis":{"intent_score":"high","summary":"Signals suggest an active evaluation.","signals":["Hiring for RevOps"],"topics":["Revenue operations"]},"conversation_strategy":{"opening":"Lead with forecast-quality improvements.","approach":"Connect operational pain to the existing planning cycle.","key_questions":["Where do forecast handoffs break down today?"]},"risks_and_challenges":{"potential_blockers":["Budget timing"],"risks":["Competing internal initiative"],"mitigations":["Offer a focused pilot with measurable outcomes."]}},"usage":{"tokens":4200,"input_tokens":3500,"cached_input_tokens":1200,"cache_write_tokens":300,"output_tokens":700,"reasoning_tokens":180,"cost_usd":0.0123,"backend_requests":1,"backend_runtime_ms":1830},"created_at":"2026-07-13T12:00:00Z","expires_at":"2026-08-12T12:00:00Z","started_at":"2026-07-13T12:00:00Z","finished_at":"2026-07-13T12:00:00Z"}},"audiences":{"summary":"Completed Audiences job","value":{"id":"job_audience_123","type":"audiences","status":"succeeded","progress":100,"project_id":"proj_123","campaign_id":"camp_123","input":{"objective":"Find VP Revenue Operations leaders at B2B SaaS companies.","target_size":100,"max_contacts_per_company":3,"model":"default"},"result":{"count":100,"result_shape":"company","generated_at":"2026-07-13T12:00:00Z","rtsa_cycle_id":"cycle_123","contacts_count":230,"avg_final_score":84.2,"max_final_score":96.0,"top_industries":[{"industry":"Software","count":64}],"icp":{"offer":"Northstar Analytics","description":"Enterprise B2B SaaS companies with complex revenue operations.","intent_topics":["revenue operations"],"industries":["Software"],"job_titles":["VP Revenue Operations"]}},"usage":{"tokens":4200,"input_tokens":3500,"cached_input_tokens":1200,"cache_write_tokens":300,"output_tokens":700,"reasoning_tokens":180,"cost_usd":0.0123,"backend_requests":1,"backend_runtime_ms":1830,"candidates":100},"stages":[{"key":"icp","label":"Ideal customer profile","status":"completed"}],"created_at":"2026-07-13T12:00:00Z","expires_at":"2026-08-12T12:00:00Z","started_at":"2026-07-13T12:00:00Z","finished_at":"2026-07-13T12:00:00Z"}}}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga"}},"/v1/playbooks/{job_id}/document":{"get":{"tags":["Playbooks"],"summary":"Retrieve the rendered playbook document","description":"Return the fully rendered, self-contained HTML playbook for a succeeded Playbooks job. Only available when the generation backend produced a rendered document (`result.document_url` is non-null).","operationId":"get_playbook_document_v1_playbooks__job_id__document_get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"The rendered playbook document.","content":{"application/json":{"schema":{},"example":"Example value"},"text/html":{"schema":{"type":"string","format":"html"},"example":"Example value"}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga"}},"/v1/usage":{"get":{"tags":["Usage"],"summary":"Retrieve project usage","description":"Return month-to-date usage and prepaid-credit information for the API key's project.","operationId":"usage_v1_usage_get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Month-to-date project usage and organization credit balance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicUsageResponse"},"example":{"project_id":"proj_123","period":"2026-07","period_start":"2026-07-01T00:00:00Z","period_end":"2026-08-01T00:00:00Z","rollup":{"requests":12,"tokens":45200,"cost_usd":1.243},"by_capability":[{"capability_key":"playbooks","requests":12,"tokens":45200,"cost_usd":1.243}],"rate_limit":{"limit":120,"window_seconds":60},"usage_tier":{"key":"tier_1","name":"Tier 1","rank":1,"rate_limit_per_minute":120,"monthly_cost_cap_usd":500.0},"quotas":[{"metric":"requests","period":"month","scope":"project","capability_key":"playbooks","limit_value":1000,"used":12,"remaining":988,"resets_at":"2026-08-01T00:00:00Z"}],"budgets":[{"period":"month","scope":"project","limit_usd":50,"spend_usd":1.243,"remaining_usd":48.757,"hard_limit":true,"resets_at":"2026-08-01T00:00:00Z"}],"credits":{"billing_enabled":true,"balance_usd":98.757,"topup_increment_usd":25.0}}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga"}},"/v1/account-coordination-assessments":{"post":{"tags":["Account Coordination"],"summary":"Create Account Coordination Assessment","operationId":"create_account_coordination_assessment_v1_account_coordination_assessments_post","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountCoordinationAssessmentCreateIn"},"example":{"key":"example-key","audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","expected_audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","company_domain":"Example company domain","expected_policy_version":"2026-07-13","reason":"Example value"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountCoordinationAssessmentOut"},"example":{"schema_version":"2026-07-13","status":"assessed","id":"acctcoord_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","policy_version":"2026-07-13","evidence":{"audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","company_domain":"Example company domain","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"outcome_ids":["outcome_aaaaaaaaaaaaaaaaaaaaaaaa"],"cutoff":"2026-07-16T00:00:00Z","member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","outcome_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","unverified_outcome_count":0},"state":"complete","disposition":"not_evaluated","flags":["account_converted"],"modifications":{"cadence_class":"standard","max_contacts":1,"window_days":1,"retry_after":"2026-07-16T00:00:00Z"},"assessment_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","outbound_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"200":{"description":"Exact replay of an immutable assessment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountCoordinationAssessmentOut"},"example":{"schema_version":"2026-07-13","status":"assessed","id":"acctcoord_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","policy_version":"2026-07-13","evidence":{"audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","company_domain":"Example company domain","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"outcome_ids":["outcome_aaaaaaaaaaaaaaaaaaaaaaaa"],"cutoff":"2026-07-16T00:00:00Z","member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","outcome_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","unverified_outcome_count":0},"state":"complete","disposition":"not_evaluated","flags":["account_converted"],"modifications":{"cadence_class":"standard","max_contacts":1,"window_days":1,"retry_after":"2026-07-16T00:00:00Z"},"assessment_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","outbound_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"Create Account Coordination Assessment. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."}},"/v1/account-coordination-assessments/{assessment_id}":{"get":{"tags":["Account Coordination"],"summary":"Get Account Coordination Assessment","operationId":"get_account_coordination_assessment_v1_account_coordination_assessments__assessment_id__get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"assessment_id","in":"path","required":true,"schema":{"type":"string","pattern":"^acctcoord_[a-f0-9]{24}$","title":"Assessment Id"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountCoordinationAssessmentOut"},"example":{"schema_version":"2026-07-13","status":"assessed","id":"acctcoord_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","policy_version":"2026-07-13","evidence":{"audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","company_domain":"Example company domain","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"outcome_ids":["outcome_aaaaaaaaaaaaaaaaaaaaaaaa"],"cutoff":"2026-07-16T00:00:00Z","member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","outcome_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","unverified_outcome_count":0},"state":"complete","disposition":"not_evaluated","flags":["account_converted"],"modifications":{"cadence_class":"standard","max_contacts":1,"window_days":1,"retry_after":"2026-07-16T00:00:00Z"},"assessment_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","outbound_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"Get Account Coordination Assessment. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."}},"/v1/audience-snapshots":{"post":{"tags":["Audience Snapshots"],"summary":"Create Audience","operationId":"create_audience_v1_audience_snapshots_post","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AudienceCreateIn"},"example":{"key":"example_key","name":"Example value","prospecting_job_id":"job_aaaaaaaaaaaaaaaaaaaaaaaa"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AudienceOut"},"example":{"id":"Example id","status":"active","idempotent_replay":true,"key":"Example key","name":"Example name","project_id":"Example project id","environment":"live","prospecting_job_id":"Example prospecting job id","prospecting_result_hash":"Example prospecting result hash","external_ref":"Example external ref","member_count":0,"review_counts":{"pending":0,"included":0,"excluded":0},"outbound_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"200":{"description":"Exact idempotent replay of an existing audience materialization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AudienceOut"},"example":{"id":"Example id","status":"active","idempotent_replay":true,"key":"Example key","name":"Example name","project_id":"Example project id","environment":"live","prospecting_job_id":"Example prospecting job id","prospecting_result_hash":"Example prospecting result hash","external_ref":"Example external ref","member_count":0,"review_counts":{"pending":0,"included":0,"excluded":0},"outbound_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga","description":"Create Audience. This is a ga operation scoped to the authenticated project or organization as documented by its response schema."},"get":{"tags":["Audience Snapshots"],"summary":"List Audiences","operationId":"list_audiences_v1_audience_snapshots_get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AudiencesResponse"},"example":{"audiences":[{"id":"Example id","status":"active","idempotent_replay":true,"key":"Example key","name":"Example name","project_id":"Example project id","environment":"live","prospecting_job_id":"Example prospecting job id","prospecting_result_hash":"Example prospecting result hash","external_ref":"Example external ref","member_count":0,"review_counts":{"pending":0,"included":0,"excluded":0},"outbound_authorized":false,"created_at":"2026-07-16T00:00:00Z"}],"next_cursor":"Example next cursor","total":0}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga","description":"List Audiences. This is a ga operation scoped to the authenticated project or organization as documented by its response schema."}},"/v1/audience-snapshots/{audience_id}":{"get":{"tags":["Audience Snapshots"],"summary":"Get Audience","operationId":"get_audience_v1_audience_snapshots__audience_id__get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"audience_id","in":"path","required":true,"schema":{"type":"string","pattern":"^audience_[a-f0-9]{24}$","title":"Audience Id"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AudienceOut"},"example":{"id":"Example id","status":"active","idempotent_replay":true,"key":"Example key","name":"Example name","project_id":"Example project id","environment":"live","prospecting_job_id":"Example prospecting job id","prospecting_result_hash":"Example prospecting result hash","external_ref":"Example external ref","member_count":0,"review_counts":{"pending":0,"included":0,"excluded":0},"outbound_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga","description":"Get Audience. This is a ga operation scoped to the authenticated project or organization as documented by its response schema."}},"/v1/audience-snapshots/{audience_id}/members":{"get":{"tags":["Audience Snapshots"],"summary":"List Audience Members","operationId":"list_audience_members_v1_audience_snapshots__audience_id__members_get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"audience_id","in":"path","required":true,"schema":{"type":"string","pattern":"^audience_[a-f0-9]{24}$","title":"Audience Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Q"}},{"name":"review_status","in":"query","required":false,"schema":{"anyOf":[{"enum":["pending","included","excluded"],"type":"string"},{"type":"null"}],"title":"Review Status"}},{"name":"qualification_status","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(qualified|rejected|unknown)$"},{"type":"null"}],"title":"Qualification Status"}},{"name":"enrichment_status","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(not_requested|pending|found|not_found|failed)$"},{"type":"null"}],"title":"Enrichment Status"}},{"name":"outreach_state","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(not_ready|ready_to_contact)$"},{"type":"null"}],"title":"Outreach State"}},{"name":"min_score","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Min Score"}},{"name":"has_evidence","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Evidence"}},{"name":"has_work_email","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Work Email"}},{"name":"prospect_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":120,"pattern":"^[^\\x00-\\x1f\\x7f]+$"},{"type":"null"}],"title":"Prospect Id"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AudienceMembersResponse"},"example":{"members":[{"id":"Example id","audience_id":"Example audience id","project_id":"Example project id","environment":"live","prospecting_job_id":"Example prospecting job id","prospecting_result_hash":"Example prospecting result hash","prospect_id":"Example prospect id","external_id":"Example external id","is_synthetic":false,"profile":{"company":{}},"qualification":{"status":"qualified","score":0.0,"confidence":0.0,"reason":"Example reason","selection_strategy":"cold_start"},"enrichment":{"status":"not_requested"},"outreach":{"state":"not_ready"},"evidence":[{"id":"Example id","source":"web","label":"Example label","confidence":0.0}],"evidence_count":0,"review_status":"pending","review_reason_code":"Example review reason code","reviewed_at":"2026-07-16T00:00:00Z","outbound_authorized":false,"created_at":"2026-07-16T00:00:00Z"}],"next_cursor":"Example next cursor","total":0}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga","description":"List Audience Members. This is a ga operation scoped to the authenticated project or organization as documented by its response schema."}},"/v1/audience-snapshots/{audience_id}/reviews":{"post":{"tags":["Audience Snapshots"],"summary":"Review Audience Members","operationId":"review_audience_members_v1_audience_snapshots__audience_id__reviews_post","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"audience_id","in":"path","required":true,"schema":{"type":"string","pattern":"^audience_[a-f0-9]{24}$","title":"Audience Id"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AudienceReviewCreateIn"},"example":{"review_key":"Example value","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"decision":"included","reason_code":"example_key"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AudienceReviewOut"},"example":{"id":"Example id","status":"recorded","idempotent_replay":true,"audience_id":"Example audience id","review_key":"Example review key","decision":"included","reason_code":"Example reason code","member_ids":["Example member ids"],"changed_count":0,"recorded_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"200":{"description":"Exact idempotent replay of an existing audience review","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AudienceReviewOut"},"example":{"id":"Example id","status":"recorded","idempotent_replay":true,"audience_id":"Example audience id","review_key":"Example review key","decision":"included","reason_code":"Example reason code","member_ids":["Example member ids"],"changed_count":0,"recorded_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga","description":"Review Audience Members. This is a ga operation scoped to the authenticated project or organization as documented by its response schema."}},"/v1/audience-snapshots/{audience_id}/export.csv":{"get":{"tags":["Audience Snapshots"],"summary":"Export Audience Csv","operationId":"export_audience_csv_v1_audience_snapshots__audience_id__export_csv_get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"audience_id","in":"path","required":true,"schema":{"type":"string","pattern":"^audience_[a-f0-9]{24}$","title":"Audience Id"}},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Q"}},{"name":"review_status","in":"query","required":false,"schema":{"anyOf":[{"enum":["pending","included","excluded"],"type":"string"},{"type":"null"}],"title":"Review Status"}},{"name":"qualification_status","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(qualified|rejected|unknown)$"},{"type":"null"}],"title":"Qualification Status"}},{"name":"enrichment_status","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(not_requested|pending|found|not_found|failed)$"},{"type":"null"}],"title":"Enrichment Status"}},{"name":"outreach_state","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(not_ready|ready_to_contact)$"},{"type":"null"}],"title":"Outreach State"}},{"name":"min_score","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Min Score"}},{"name":"has_evidence","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Evidence"}},{"name":"has_work_email","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Work Email"}},{"name":"prospect_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":120,"pattern":"^[^\\x00-\\x1f\\x7f]+$"},{"type":"null"}],"title":"Prospect Id"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Deterministic RFC 4180 audience export","content":{"text/csv":{"schema":{"type":"string"},"example":"Example value"}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga","description":"Export Audience Csv. This is a ga operation scoped to the authenticated project or organization as documented by its response schema."}},"/v1/brands":{"post":{"tags":["Brands"],"summary":"Research a brand and build its guideline","description":"Create a Brand resource, enqueue evidence-backed web research, and return its typed Brands job. Poll `GET /v1/jobs/{job_id}` until terminal, then read the versioned guideline from the result path. Send `Idempotency-Key` so an ambiguous retry replays the original response for 24 hours.","operationId":"create_brand_v1_brands_post","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":255},{"type":"null"}],"description":"Deduplicates brand creation/research within the authenticated project for 24 hours.","title":"Idempotency-Key"},"description":"Deduplicates brand creation/research within the authenticated project for 24 hours."},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicBrandCreateIn"},"example":{"company_name":"Acme Corporation","website_url":"https://acme.example","key":"acme_corporation","is_default":false}}}},"responses":{"202":{"description":"Accepted Brands research job. The typed result is null until the job succeeds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicBrandJobResponse"},"example":{"id":"job_brand_123","type":"brands","status":"succeeded","progress":100,"project_id":"proj_123","input":{"brand_profile_id":"brand_01h8z3m2q7","company_name":"Acme Corporation","website_url":"https://acme.example","company_name_supplied":true},"result":{"brand_profile_id":"brand_01h8z3m2q7","schema_version":"2026-07-16","revision":1,"guideline_hash":"9b5de1c78bd1d21b6168cf6b73e186dcf9a875606a0e81025fcb8015e089f9f1","source_count":8,"guideline_path":"/v1/brands/brand_01h8z3m2q7/guideline"},"usage":{"tokens":8400,"input_tokens":3500,"cached_input_tokens":1200,"cache_write_tokens":300,"output_tokens":700,"reasoning_tokens":180,"cost_usd":0.0123,"backend_requests":6,"backend_runtime_ms":1830},"created_at":"2026-07-13T12:00:00Z","expires_at":"2026-08-12T12:00:00Z","started_at":"2026-07-13T12:00:00Z","finished_at":"2026-07-13T12:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga"},"get":{"tags":["Brands"],"summary":"List active brands","description":"List active Brand resources for the authenticated organization, including latest research state, guideline revision, and provenance source count. Internal branding snapshots are never returned.","operationId":"list_brands_v1_brands_get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Active brands visible to the authenticated organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicBrandsResponse"},"example":{"brands":[{"id":"brand_01h8z3m2q7","name":"Acme Corporation","key":"acme_corporation","company_url":"https://acme.example","extraction_status":"ready","research_status":"ready","research_job_id":"job_brand_123","guideline_available":true,"guideline_revision":1,"source_count":8,"is_default":true,"archived":false,"created_at":"2026-07-13T12:00:00Z","updated_at":"2026-07-13T12:00:00Z"}]}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga"}},"/v1/brands/{brand_id}":{"get":{"tags":["Brands"],"summary":"Get a brand","description":"Read one organization-owned Brand resource and its latest research state without exposing raw provider data.","operationId":"get_brand_v1_brands__brand_id__get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","title":"Brand Id"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Brand resource and latest guideline-research state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicBrand"},"example":{"id":"brand_01h8z3m2q7","name":"Acme Corporation","key":"acme_corporation","company_url":"https://acme.example","extraction_status":"ready","research_status":"ready","research_job_id":"job_brand_123","guideline_available":true,"guideline_revision":1,"source_count":8,"is_default":true,"archived":false,"created_at":"2026-07-13T12:00:00Z","updated_at":"2026-07-13T12:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga"}},"/v1/brands/{brand_id}/research":{"post":{"tags":["Brands"],"summary":"Refresh a brand guideline from current web evidence","description":"Enqueue a new evidence-backed guideline revision for an existing active Brand. If research is already queued or running, return that active job instead of creating a duplicate.","operationId":"research_brand_v1_brands__brand_id__research_post","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","title":"Brand Id"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":255},{"type":"null"}],"description":"Deduplicates brand creation/research within the authenticated project for 24 hours.","title":"Idempotency-Key"},"description":"Deduplicates brand creation/research within the authenticated project for 24 hours."},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"202":{"description":"Accepted or already-active Brands research job.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicBrandJobResponse"},"example":{"id":"job_brand_123","type":"brands","status":"succeeded","progress":100,"project_id":"proj_123","input":{"brand_profile_id":"brand_01h8z3m2q7","company_name":"Acme Corporation","website_url":"https://acme.example","company_name_supplied":true},"result":{"brand_profile_id":"brand_01h8z3m2q7","schema_version":"2026-07-16","revision":1,"guideline_hash":"9b5de1c78bd1d21b6168cf6b73e186dcf9a875606a0e81025fcb8015e089f9f1","source_count":8,"guideline_path":"/v1/brands/brand_01h8z3m2q7/guideline"},"usage":{"tokens":8400,"input_tokens":3500,"cached_input_tokens":1200,"cache_write_tokens":300,"output_tokens":700,"reasoning_tokens":180,"cost_usd":0.0123,"backend_requests":6,"backend_runtime_ms":1830},"created_at":"2026-07-13T12:00:00Z","expires_at":"2026-08-12T12:00:00Z","started_at":"2026-07-13T12:00:00Z","finished_at":"2026-07-13T12:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga"}},"/v1/brands/{brand_id}/guideline":{"get":{"tags":["Brands"],"summary":"Get a standardized brand guideline","description":"Read the current immutable, hash-addressable guideline document with identity, foundations, audience, positioning, voice, messaging, visual rules, applications, governance, and research provenance.","operationId":"get_brand_guideline_v1_brands__brand_id__guideline_get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","title":"Brand Id"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Current canonical Brand guideline and deterministic Markdown rendering.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandGuidelineDocument"},"example":{"identity":{"name":"Acme Corporation","website":"https://acme.example","tagline":"Build what matters","short_description":"Acme builds workflow software for growing teams.","long_description":"Acme helps growing teams coordinate work with practical workflow software.","evidence":{"source_ids":["src_official_home"],"confidence":"high"}},"foundations":{"mission":"Make important work easier to coordinate."},"audience":{"audience_principles":["Write for busy operations leaders."]},"positioning":{"category":"Workflow software","value_proposition":"Clear coordination without added process."},"voice":{"summary":"Clear, practical, and optimistic.","principles":["Lead with the useful point."]},"messaging":{"elevator_pitch":"Acme helps growing teams coordinate important work."},"visual":{"colors":[{"name":"Acme Blue","role":"primary","hex":"#2157D5","rgb":"33, 87, 213","usage":"Primary actions and key brand moments.","source_ids":["src_official_brand"]}]},"applications":{"documents":["Use concise headings and generous whitespace."]},"governance":{"approval_notes":["A human brand owner must approve external publication."]},"research":{"sources":[{"id":"src_official_home","url":"https://acme.example","title":"Acme Corporation","publisher":"Acme Corporation","source_type":"official"},{"id":"src_official_brand","url":"https://acme.example/brand","title":"Acme brand resources","publisher":"Acme Corporation","source_type":"asset"}],"limitations":["Only publicly available evidence was used."],"assumptions":[]},"schema_version":"2026-07-16","brand_profile_id":"brand_01h8z3m2q7","revision":1,"generated_at":"2026-07-16T12:00:00Z","generation":{"provider":"openai","model":"gpt-5.6","workflow":"brand_guideline_research"},"guideline_hash":"9b5de1c78bd1d21b6168cf6b73e186dcf9a875606a0e81025fcb8015e089f9f1","markdown":"# Acme Corporation — Brand Guidelines\n\n## Identity\n\nAcme builds workflow software for growing teams."}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga"}},"/v1/jobs/{parent_job_id}/continuations":{"post":{"tags":["Jobs"],"summary":"Create Prospecting Continuation","operationId":"create_prospecting_continuation_v1_jobs__parent_job_id__continuations_post","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"parent_job_id","in":"path","required":true,"schema":{"type":"string","pattern":"^job_[a-f0-9]{24}$","title":"Parent Job Id"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectingContinuationRequest"},"example":{"additional_prospect_limit":1,"continuation_key":"example-key"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectingContinuationResponse"},"example":{"id":"continuation_aaaaaaaaaaaaaaaaaaaaaaaa","status":"accepted","idempotent_replay":true,"continuation_key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","parent_job_id":"job_aaaaaaaaaaaaaaaaaaaaaaaa","parent_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","constraints":{"additional_prospect_limit":1},"child_job":{"id":"job_playbook_123","status":"succeeded","progress":100,"project_id":"proj_123","usage":{"backend_requests":1,"backend_runtime_ms":1830,"cache_write_tokens":300,"cached_input_tokens":1200,"cost_usd":0.0123,"input_tokens":3500,"output_tokens":700,"reasoning_tokens":180,"tokens":4200},"created_at":"2026-07-13T12:00:00Z","expires_at":"2026-08-12T12:00:00Z","type":"prospecting","input":{"campaign_name":"Example campaign name","product_info":"Example product info","objective":"Example objective"}},"outbound_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"200":{"description":"Exact idempotent replay of an existing continuation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectingContinuationResponse"},"example":{"id":"continuation_aaaaaaaaaaaaaaaaaaaaaaaa","status":"accepted","idempotent_replay":true,"continuation_key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","parent_job_id":"job_aaaaaaaaaaaaaaaaaaaaaaaa","parent_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","constraints":{"additional_prospect_limit":1},"child_job":{"id":"job_playbook_123","status":"succeeded","progress":100,"project_id":"proj_123","usage":{"backend_requests":1,"backend_runtime_ms":1830,"cache_write_tokens":300,"cached_input_tokens":1200,"cost_usd":0.0123,"input_tokens":3500,"output_tokens":700,"reasoning_tokens":180,"tokens":4200},"created_at":"2026-07-13T12:00:00Z","expires_at":"2026-08-12T12:00:00Z","type":"prospecting","input":{"campaign_name":"Example campaign name","product_info":"Example product info","objective":"Example objective"}},"outbound_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"Create Prospecting Continuation. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."}},"/v1/message-template-revisions/generate":{"post":{"tags":["Message Templates"],"summary":"Generate an immutable message-template revision","description":"Start a bounded OpenAI Responses job from approved GTM context. The server converts only allowlisted placeholders into the closed structural template format, applies the published quality gate, persists the next immutable revision, and never enqueues or sends a message.","operationId":"generate_message_template_revision_v1_message_template_revisions_generate_post","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":255},{"type":"null"}],"description":"Deduplicates this generation request in the project for 24 hours.","title":"Idempotency-Key"},"description":"Deduplicates this generation request in the project for 24 hours."},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageTemplateGenerateIn"},"example":{"template_key":"example-key","name":"Example name","audience":"Example audience","objective":"Example objective","desired_next_step":"Example desired next step","reason":"Example value"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageTemplateJobResponse"},"example":{"id":"job_playbook_123","status":"succeeded","progress":100,"project_id":"proj_123","usage":{"backend_requests":1,"backend_runtime_ms":1830,"cache_write_tokens":300,"cached_input_tokens":1200,"cost_usd":0.0123,"input_tokens":3500,"output_tokens":700,"reasoning_tokens":180,"tokens":4200},"created_at":"2026-07-13T12:00:00Z","expires_at":"2026-08-12T12:00:00Z","type":"message_templates","input":{"template_key":"example-key","name":"Example name","audience":"Example audience","objective":"Example objective","desired_next_step":"Example desired next step","reason":"Example value"}}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview"}},"/v1/message-template-revisions/{revision_id}/prospect-message":{"post":{"tags":["Message Templates"],"summary":"Personalize an approval-only message for a retained prospect","description":"Verify platform policy, suppression, identity, qualification, and retained evidence for one prospect from an unexpired succeeded Prospecting job, then deterministically render the selected immutable revision. Personalization makes no provider call, and passing copy remains an approval artifact with no send authority.","operationId":"generate_prospect_message_v1_message_template_revisions__revision_id__prospect_message_post","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"revision_id","in":"path","required":true,"schema":{"type":"string","pattern":"^msgtemplate_[a-f0-9]{24}$","title":"Revision Id"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":255},{"type":"null"}],"description":"Deduplicates this generation request in the project for 24 hours.","title":"Idempotency-Key"},"description":"Deduplicates this generation request in the project for 24 hours."},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectMessageGenerateIn"},"example":{"prospecting_job_id":"job_aaaaaaaaaaaaaaaaaaaaaaaa","prospect_id":"Example value","reason":"Example value"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageTemplateJobResponse"},"example":{"id":"job_playbook_123","status":"succeeded","progress":100,"project_id":"proj_123","usage":{"backend_requests":1,"backend_runtime_ms":1830,"cache_write_tokens":300,"cached_input_tokens":1200,"cost_usd":0.0123,"input_tokens":3500,"output_tokens":700,"reasoning_tokens":180,"tokens":4200},"created_at":"2026-07-13T12:00:00Z","expires_at":"2026-08-12T12:00:00Z","type":"message_templates","input":{"template_key":"example-key","name":"Example name","audience":"Example audience","objective":"Example objective","desired_next_step":"Example desired next step","reason":"Example value"}}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview"}},"/v1/message-template-revisions":{"post":{"tags":["Message Templates"],"summary":"Create Message Template Revision","operationId":"create_message_template_revision_v1_message_template_revisions_post","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageTemplateRevisionCreateIn"},"example":{"body":[{"content":[{"kind":"text","text":"Kia ora."}],"kind":"paragraph"},{"kind":"opt_out_notice"}],"channel":"email","expected_policy_version":"2026-07-13","expected_previous_template_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","language":"en-nz","name":"First-touch introduction","purpose":"gtm_outreach","reason":"Publish a reviewed structural template for exact rendering.","revision_number":2,"subject":[{"kind":"text","text":"A practical idea for "},{"key":"contact.firstname","kind":"variable"}],"template_key":"first-touch","variables":[{"classification":"recipient_personal","key":"contact.firstname","max_length":50,"required":true}]}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageTemplateRevisionOut"},"example":{"schema_version":"2026-07-13","status":"active","availability":"render_only","id":"msgtemplate_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"template_key":"example-key","revision_number":1,"name":"Example value","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","channel":"email","purpose":"gtm_outreach","language":"en-nz","variables":[{"key":"contact.firstname","classification":"recipient_personal","required":true,"max_length":1}],"subject":[{"kind":"text","text":"Example text"}],"body":[{"kind":"paragraph","content":[{"kind":"text","text":"Example text"}]},{"kind":"paragraph","content":[{"kind":"text","text":"Example text"}]}],"policy_version":"2026-07-13","template_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","previous_revision_id":"msgtemplate_aaaaaaaaaaaaaaaaaaaaaaaa","previous_template_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","arbitrary_template_code_accepted":false,"raw_html_accepted":false,"variable_values_stored":false,"attachment_uploads_accepted":false,"tracking_enabled":false,"provider_requests_made":0,"messages_enqueued":0,"messages_sent":0,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"200":{"description":"Exact replay of an immutable message-template revision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageTemplateRevisionOut"},"example":{"schema_version":"2026-07-13","status":"active","availability":"render_only","id":"msgtemplate_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"template_key":"example-key","revision_number":1,"name":"Example value","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","channel":"email","purpose":"gtm_outreach","language":"en-nz","variables":[{"key":"contact.firstname","classification":"recipient_personal","required":true,"max_length":1}],"subject":[{"kind":"text","text":"Example text"}],"body":[{"kind":"paragraph","content":[{"kind":"text","text":"Example text"}]},{"kind":"paragraph","content":[{"kind":"text","text":"Example text"}]}],"policy_version":"2026-07-13","template_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","previous_revision_id":"msgtemplate_aaaaaaaaaaaaaaaaaaaaaaaa","previous_template_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","arbitrary_template_code_accepted":false,"raw_html_accepted":false,"variable_values_stored":false,"attachment_uploads_accepted":false,"tracking_enabled":false,"provider_requests_made":0,"messages_enqueued":0,"messages_sent":0,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"Create Message Template Revision. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."},"get":{"tags":["Message Templates"],"summary":"List Message Template Revisions","operationId":"list_message_template_revisions_v1_message_template_revisions_get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"default":0,"title":"Offset"}},{"name":"template_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},{"type":"null"}],"title":"Template Key"}},{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":2,"maxLength":24,"pattern":"^[a-z]{2,3}(?:-[a-z0-9]{2,8}){0,2}$"},{"type":"null"}],"title":"Language"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageTemplateRevisionListOut"},"example":{"schema_version":"2026-07-13","availability":"render_only","revisions":[{"schema_version":"2026-07-13","status":"active","availability":"render_only","id":"msgtemplate_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"template_key":"example-key","revision_number":1,"name":"Example value","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","channel":"email","purpose":"gtm_outreach","language":"en-nz","variables":[{"key":"contact.firstname","classification":"recipient_personal","required":true,"max_length":1}],"subject":[{"kind":"text","text":"Example text"}],"body":[{"kind":"paragraph","content":[{"kind":"text","text":"Example text"}]},{"kind":"paragraph","content":[{"kind":"text","text":"Example text"}]}],"policy_version":"2026-07-13","template_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","previous_revision_id":"msgtemplate_aaaaaaaaaaaaaaaaaaaaaaaa","previous_template_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","arbitrary_template_code_accepted":false,"raw_html_accepted":false,"variable_values_stored":false,"attachment_uploads_accepted":false,"tracking_enabled":false,"provider_requests_made":0,"messages_enqueued":0,"messages_sent":0,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}],"total":0,"limit":1,"offset":0,"provider_requests_made":0,"messages_sent":0,"outbound_authorized":false}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"List Message Template Revisions. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."}},"/v1/message-template-revisions/{revision_id}":{"get":{"tags":["Message Templates"],"summary":"Get Message Template Revision","operationId":"get_message_template_revision_v1_message_template_revisions__revision_id__get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"revision_id","in":"path","required":true,"schema":{"type":"string","pattern":"^msgtemplate_[a-f0-9]{24}$","title":"Revision Id"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageTemplateRevisionOut"},"example":{"schema_version":"2026-07-13","status":"active","availability":"render_only","id":"msgtemplate_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"template_key":"example-key","revision_number":1,"name":"Example value","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","channel":"email","purpose":"gtm_outreach","language":"en-nz","variables":[{"key":"contact.firstname","classification":"recipient_personal","required":true,"max_length":1}],"subject":[{"kind":"text","text":"Example text"}],"body":[{"kind":"paragraph","content":[{"kind":"text","text":"Example text"}]},{"kind":"paragraph","content":[{"kind":"text","text":"Example text"}]}],"policy_version":"2026-07-13","template_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","previous_revision_id":"msgtemplate_aaaaaaaaaaaaaaaaaaaaaaaa","previous_template_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","arbitrary_template_code_accepted":false,"raw_html_accepted":false,"variable_values_stored":false,"attachment_uploads_accepted":false,"tracking_enabled":false,"provider_requests_made":0,"messages_enqueued":0,"messages_sent":0,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"Get Message Template Revision. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."}},"/v1/message-template-revisions/{revision_id}/render":{"post":{"tags":["Message Templates"],"summary":"Render Message Template Revision","operationId":"render_message_template_revision_v1_message_template_revisions__revision_id__render_post","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"revision_id","in":"path","required":true,"schema":{"type":"string","pattern":"^msgtemplate_[a-f0-9]{24}$","title":"Revision Id"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageTemplateRenderIn"},"example":{"reference":"example-key","expected_template_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","values":{},"expected_policy_version":"2026-07-13","fail_closed_on_error":true}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageTemplateRenderOut"},"example":{"schema_version":"2026-07-13","status":"rendered","availability":"render_only","reference":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","template_revision_id":"msgtemplate_aaaaaaaaaaaaaaaaaaaaaaaa","template_key":"example-key","revision_number":1,"language":"en-nz","policy_version":"2026-07-13","template_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","subject":"Example subject","text_body":"Example text body","html_body":"Example html body","values_used":["contact.firstname"],"missing_optional_variables":["contact.firstname"],"opt_out_notice_included":true,"variable_values_escaped_for_html":true,"fail_closed_on_error":true,"approval_artifact":{"artifact_kind":"message","artifact_id":"msgart_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","artifact_version":"2026-07-13","artifact_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},"arbitrary_template_code_accepted":false,"raw_html_accepted":false,"variable_values_stored":false,"attachment_uploads_accepted":false,"tracking_enabled":false,"provider_requests_made":0,"messages_enqueued":0,"messages_sent":0,"outbound_authorized":false,"crm_mutation_authorized":false,"rendered_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"Render Message Template Revision. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."}},"/v1/enrichment-specifications":{"post":{"tags":["Enrichment"],"summary":"Create Enrichment Specification","operationId":"create_enrichment_specification_v1_enrichment_specifications_post","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichmentSpecificationCreateIn"},"example":{"key":"example-key","audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","expected_audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","selection":{"mode":"included"},"fields":["company_description"],"expected_policy_version":"2026-07-13","reason":"Example value"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichmentSpecificationOut"},"example":{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"enrichspec_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","policy_version":"2026-07-13","selection":{"mode":"included","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"member_count":1,"member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},"field_specs":[{"field":"company_description","target":"company","value_type":"text","required_connector_capability":"people-enrich","max_freshness_days":1,"evidence_required":true}],"specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"provider_requests_made":false,"records_processed":0,"records_enriched":0,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"200":{"description":"Exact replay of an immutable specification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichmentSpecificationOut"},"example":{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"enrichspec_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","policy_version":"2026-07-13","selection":{"mode":"included","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"member_count":1,"member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},"field_specs":[{"field":"company_description","target":"company","value_type":"text","required_connector_capability":"people-enrich","max_freshness_days":1,"evidence_required":true}],"specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"provider_requests_made":false,"records_processed":0,"records_enriched":0,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"Create Enrichment Specification. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."},"get":{"tags":["Enrichment"],"summary":"List Enrichment Specifications","operationId":"list_enrichment_specifications_v1_enrichment_specifications_get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"default":0,"title":"Offset"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichmentSpecificationListOut"},"example":{"specifications":[{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"enrichspec_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","policy_version":"2026-07-13","selection":{"mode":"included","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"member_count":1,"member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},"field_specs":[{"field":"company_description","target":"company","value_type":"text","required_connector_capability":"people-enrich","max_freshness_days":1,"evidence_required":true}],"specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"provider_requests_made":false,"records_processed":0,"records_enriched":0,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}],"total":0,"limit":1,"offset":0,"availability":"contract_only","execution_available":false,"provider_requests_made":false}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"List Enrichment Specifications. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."}},"/v1/enrichment-specifications/{specification_id}":{"get":{"tags":["Enrichment"],"summary":"Get Enrichment Specification","operationId":"get_enrichment_specification_v1_enrichment_specifications__specification_id__get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"specification_id","in":"path","required":true,"schema":{"type":"string","pattern":"^enrichspec_[a-f0-9]{24}$","title":"Specification Id"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichmentSpecificationOut"},"example":{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"enrichspec_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","policy_version":"2026-07-13","selection":{"mode":"included","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"member_count":1,"member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},"field_specs":[{"field":"company_description","target":"company","value_type":"text","required_connector_capability":"people-enrich","max_freshness_days":1,"evidence_required":true}],"specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"provider_requests_made":false,"records_processed":0,"records_enriched":0,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"Get Enrichment Specification. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."}},"/v1/data-intake-specifications":{"post":{"tags":["Data Intake"],"summary":"Create Data Intake Specification","operationId":"create_data_intake_specification_v1_data_intake_specifications_post","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataIntakeSpecificationCreateIn"},"example":{"key":"example-key","source":{"source":"overture_places","version":"2026-07-15.1"},"selection":{"max_records":1},"fields":["source_record_id","source_record_id"],"deduplication":{"match_keys":["source_record_id"]},"purpose":"account_discovery","retention_days":1,"expected_policy_version":"2026-07-13","reason":"Example value"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataIntakeSpecificationOut"},"example":{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"intakespec_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","source":{"source":"overture_places","version":"2026-07-15.1"},"source_policy":{"source":"overture_places","display_name":"Example display name","access_mode":"anonymous_public_snapshot","credential_requirement":"none","official_documentation_url":"https://example.com","required_connector_capability":"public-dataset-read","snapshot_manifest_required":true,"version_availability_revalidation_required":true,"terms_review_required":true,"attribution_required":true,"maximum_records":1},"selection":{"max_records":1},"field_specs":[{"field":"source_record_id","value_type":"identifier","data_classification":"public_organization","evidence_required":true},{"field":"source_record_id","value_type":"identifier","data_classification":"public_organization","evidence_required":true}],"deduplication":{"match_keys":["source_record_id"]},"purpose":"account_discovery","retention_days":1,"policy_version":"2026-07-13","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"source_requests_made":0,"bytes_received":0,"records_read":0,"records_staged":0,"records_written":0,"matches_attempted":0,"upload_authorized":false,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"200":{"description":"Exact replay of an immutable specification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataIntakeSpecificationOut"},"example":{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"intakespec_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","source":{"source":"overture_places","version":"2026-07-15.1"},"source_policy":{"source":"overture_places","display_name":"Example display name","access_mode":"anonymous_public_snapshot","credential_requirement":"none","official_documentation_url":"https://example.com","required_connector_capability":"public-dataset-read","snapshot_manifest_required":true,"version_availability_revalidation_required":true,"terms_review_required":true,"attribution_required":true,"maximum_records":1},"selection":{"max_records":1},"field_specs":[{"field":"source_record_id","value_type":"identifier","data_classification":"public_organization","evidence_required":true},{"field":"source_record_id","value_type":"identifier","data_classification":"public_organization","evidence_required":true}],"deduplication":{"match_keys":["source_record_id"]},"purpose":"account_discovery","retention_days":1,"policy_version":"2026-07-13","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"source_requests_made":0,"bytes_received":0,"records_read":0,"records_staged":0,"records_written":0,"matches_attempted":0,"upload_authorized":false,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"Create Data Intake Specification. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."},"get":{"tags":["Data Intake"],"summary":"List Data Intake Specifications","operationId":"list_data_intake_specifications_v1_data_intake_specifications_get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"default":0,"title":"Offset"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataIntakeSpecificationListOut"},"example":{"specifications":[{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"intakespec_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","source":{"source":"overture_places","version":"2026-07-15.1"},"source_policy":{"source":"overture_places","display_name":"Example display name","access_mode":"anonymous_public_snapshot","credential_requirement":"none","official_documentation_url":"https://example.com","required_connector_capability":"public-dataset-read","snapshot_manifest_required":true,"version_availability_revalidation_required":true,"terms_review_required":true,"attribution_required":true,"maximum_records":1},"selection":{"max_records":1},"field_specs":[{"field":"source_record_id","value_type":"identifier","data_classification":"public_organization","evidence_required":true},{"field":"source_record_id","value_type":"identifier","data_classification":"public_organization","evidence_required":true}],"deduplication":{"match_keys":["source_record_id"]},"purpose":"account_discovery","retention_days":1,"policy_version":"2026-07-13","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"source_requests_made":0,"bytes_received":0,"records_read":0,"records_staged":0,"records_written":0,"matches_attempted":0,"upload_authorized":false,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}],"total":0,"limit":1,"offset":0,"availability":"contract_only","execution_available":false,"source_requests_made":0}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"List Data Intake Specifications. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."}},"/v1/data-intake-specifications/{specification_id}":{"get":{"tags":["Data Intake"],"summary":"Get Data Intake Specification","operationId":"get_data_intake_specification_v1_data_intake_specifications__specification_id__get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"specification_id","in":"path","required":true,"schema":{"type":"string","pattern":"^intakespec_[a-f0-9]{24}$","title":"Specification Id"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataIntakeSpecificationOut"},"example":{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"intakespec_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","source":{"source":"overture_places","version":"2026-07-15.1"},"source_policy":{"source":"overture_places","display_name":"Example display name","access_mode":"anonymous_public_snapshot","credential_requirement":"none","official_documentation_url":"https://example.com","required_connector_capability":"public-dataset-read","snapshot_manifest_required":true,"version_availability_revalidation_required":true,"terms_review_required":true,"attribution_required":true,"maximum_records":1},"selection":{"max_records":1},"field_specs":[{"field":"source_record_id","value_type":"identifier","data_classification":"public_organization","evidence_required":true},{"field":"source_record_id","value_type":"identifier","data_classification":"public_organization","evidence_required":true}],"deduplication":{"match_keys":["source_record_id"]},"purpose":"account_discovery","retention_days":1,"policy_version":"2026-07-13","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"source_requests_made":0,"bytes_received":0,"records_read":0,"records_staged":0,"records_written":0,"matches_attempted":0,"upload_authorized":false,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"Get Data Intake Specification. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."}},"/v1/offers":{"post":{"tags":["Offers"],"summary":"Create an Offer","description":"Create structured selling context under an active Brand. Offer creation performs no research, generation, provider request, pricing calculation, or outbound action.","operationId":"create_offer_v1_offers_post","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/app__routers__v1_offers__OfferCreateIn"},"example":{"brand_profile_id":"Example brand profile id","name":"Example name"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfferOut"},"example":{"id":"Example id","org_id":"Example org id","brand_profile_id":"Example brand profile id","name":"Example name","key":"Example key","description":"Example description","value_props":["Example value props"],"proof_points":["Example proof points"],"pricing_model":"Example pricing model","icp":{},"stage_fit":["Example stage fit"],"status":"Example status","archived":true,"created_at":"Example created at","updated_at":"Example updated at"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga"},"get":{"tags":["Offers"],"summary":"List Offers","description":"List the authenticated organization's Offer catalog, optionally including archived Offers.","operationId":"list_offers_v1_offers_get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"include_archived","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Archived"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffersResponse"},"example":{"offers":[{"id":"Example id","org_id":"Example org id","brand_profile_id":"Example brand profile id","name":"Example name","key":"Example key","description":"Example description","value_props":["Example value props"],"proof_points":["Example proof points"],"pricing_model":"Example pricing model","icp":{},"stage_fit":["Example stage fit"],"status":"Example status","archived":true,"created_at":"Example created at","updated_at":"Example updated at"}]}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga"}},"/v1/offers/{offer_id}":{"get":{"tags":["Offers"],"summary":"Retrieve an Offer","description":"Return one Offer when it belongs to the authenticated organization.","operationId":"get_offer_v1_offers__offer_id__get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"offer_id","in":"path","required":true,"schema":{"type":"string","title":"Offer Id"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfferOut"},"example":{"id":"Example id","org_id":"Example org id","brand_profile_id":"Example brand profile id","name":"Example name","key":"Example key","description":"Example description","value_props":["Example value props"],"proof_points":["Example proof points"],"pricing_model":"Example pricing model","icp":{},"stage_fit":["Example stage fit"],"status":"Example status","archived":true,"created_at":"Example created at","updated_at":"Example updated at"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga"}},"/v1/professional-network-specifications":{"post":{"tags":["Professional Network"],"summary":"Create Professional Network Specification","operationId":"create_professional_network_specification_v1_professional_network_specifications_post","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfessionalNetworkSpecificationCreateIn"},"example":{"key":"example-key","audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","expected_audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","selection":{"mode":"included"},"connection":{"connection_id":"conn_aaaaaaaaaaaaaaaaaaaaaaaa","expected_manifest_version":"2026-07-14","expected_credentials_version":1},"display_components":["profile_summary"],"purpose":"crm_sync","expected_policy_version":"2026-07-13","reason":"Example value"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfessionalNetworkSpecificationOut"},"example":{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"pronet_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","selection":{"mode":"included","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"member_count":1,"member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","member_bindings":[{"id":"audmem_aaaaaaaaaaaaaaaaaaaaaaaa","source_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","review_status":"included","snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","identity_reference_present":true}]},"connection":{"connection_id":"conn_aaaaaaaaaaaaaaaaaaaaaaaa","provider_key":"linkedin-sales-navigator","manifest_version":"2026-07-14","credentials_version":1,"configured_fields":["Example configured fields","Example configured fields","Example configured fields","Example configured fields"],"status":"configured","live_verification_status":"not_run","credentials_decrypted":false,"access_token_stored":false,"member_password_stored":false,"browser_session_stored":false},"source_policy":{"provider":"linkedin_sales_navigator","display_name":"LinkedIn Sales Navigator","program":"sales_navigator_application_platform","operation":"display_services","integration_mode":"official_api_oauth2","oauth_flow":"member_authorization","required_scopes":["r_sales_nav_display"],"connector_manifest_key":"linkedin-sales-navigator","partner_approval_required":true,"new_partner_intake_available":false,"availability_observed_at":"2026-07-13","display_only":true,"provider_content_storage_authorized":false,"official_program_documentation_url":"https://example.com","official_display_documentation_url":"https://example.com","official_access_documentation_url":"https://example.com","official_api_terms_url":"https://example.com","official_user_agreement_url":"https://example.com","maximum_members":25},"display_components":["profile_summary"],"purpose":"crm_sync","policy_version":"2026-07-13","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"provider_requests_made":0,"network_requests_made":0,"browser_requests_made":0,"profiles_matched":0,"profiles_displayed":0,"provider_records_read":0,"provider_content_stored":false,"non_official_content_accepted":false,"raw_profile_url_accepted":false,"raw_profile_handle_accepted":false,"raw_search_query_accepted":false,"member_credentials_accepted":false,"session_cookie_accepted":false,"browser_automation_available":false,"login_automation_available":false,"profile_scraping_available":false,"company_scraping_available":false,"post_scraping_available":false,"job_scraping_available":false,"contact_extraction_available":false,"email_extraction_available":false,"message_send_authorized":false,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"200":{"description":"Exact replay of an immutable specification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfessionalNetworkSpecificationOut"},"example":{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"pronet_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","selection":{"mode":"included","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"member_count":1,"member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","member_bindings":[{"id":"audmem_aaaaaaaaaaaaaaaaaaaaaaaa","source_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","review_status":"included","snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","identity_reference_present":true}]},"connection":{"connection_id":"conn_aaaaaaaaaaaaaaaaaaaaaaaa","provider_key":"linkedin-sales-navigator","manifest_version":"2026-07-14","credentials_version":1,"configured_fields":["Example configured fields","Example configured fields","Example configured fields","Example configured fields"],"status":"configured","live_verification_status":"not_run","credentials_decrypted":false,"access_token_stored":false,"member_password_stored":false,"browser_session_stored":false},"source_policy":{"provider":"linkedin_sales_navigator","display_name":"LinkedIn Sales Navigator","program":"sales_navigator_application_platform","operation":"display_services","integration_mode":"official_api_oauth2","oauth_flow":"member_authorization","required_scopes":["r_sales_nav_display"],"connector_manifest_key":"linkedin-sales-navigator","partner_approval_required":true,"new_partner_intake_available":false,"availability_observed_at":"2026-07-13","display_only":true,"provider_content_storage_authorized":false,"official_program_documentation_url":"https://example.com","official_display_documentation_url":"https://example.com","official_access_documentation_url":"https://example.com","official_api_terms_url":"https://example.com","official_user_agreement_url":"https://example.com","maximum_members":25},"display_components":["profile_summary"],"purpose":"crm_sync","policy_version":"2026-07-13","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"provider_requests_made":0,"network_requests_made":0,"browser_requests_made":0,"profiles_matched":0,"profiles_displayed":0,"provider_records_read":0,"provider_content_stored":false,"non_official_content_accepted":false,"raw_profile_url_accepted":false,"raw_profile_handle_accepted":false,"raw_search_query_accepted":false,"member_credentials_accepted":false,"session_cookie_accepted":false,"browser_automation_available":false,"login_automation_available":false,"profile_scraping_available":false,"company_scraping_available":false,"post_scraping_available":false,"job_scraping_available":false,"contact_extraction_available":false,"email_extraction_available":false,"message_send_authorized":false,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"Create Professional Network Specification. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."},"get":{"tags":["Professional Network"],"summary":"List Professional Network Specifications","operationId":"list_professional_network_specifications_v1_professional_network_specifications_get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"default":0,"title":"Offset"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfessionalNetworkSpecificationListOut"},"example":{"schema_version":"2026-07-13","availability":"contract_only","specifications":[{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"pronet_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","selection":{"mode":"included","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"member_count":1,"member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","member_bindings":[{"id":"audmem_aaaaaaaaaaaaaaaaaaaaaaaa","source_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","review_status":"included","snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","identity_reference_present":true}]},"connection":{"connection_id":"conn_aaaaaaaaaaaaaaaaaaaaaaaa","provider_key":"linkedin-sales-navigator","manifest_version":"2026-07-14","credentials_version":1,"configured_fields":["Example configured fields","Example configured fields","Example configured fields","Example configured fields"],"status":"configured","live_verification_status":"not_run","credentials_decrypted":false,"access_token_stored":false,"member_password_stored":false,"browser_session_stored":false},"source_policy":{"provider":"linkedin_sales_navigator","display_name":"LinkedIn Sales Navigator","program":"sales_navigator_application_platform","operation":"display_services","integration_mode":"official_api_oauth2","oauth_flow":"member_authorization","required_scopes":["r_sales_nav_display"],"connector_manifest_key":"linkedin-sales-navigator","partner_approval_required":true,"new_partner_intake_available":false,"availability_observed_at":"2026-07-13","display_only":true,"provider_content_storage_authorized":false,"official_program_documentation_url":"https://example.com","official_display_documentation_url":"https://example.com","official_access_documentation_url":"https://example.com","official_api_terms_url":"https://example.com","official_user_agreement_url":"https://example.com","maximum_members":25},"display_components":["profile_summary"],"purpose":"crm_sync","policy_version":"2026-07-13","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"provider_requests_made":0,"network_requests_made":0,"browser_requests_made":0,"profiles_matched":0,"profiles_displayed":0,"provider_records_read":0,"provider_content_stored":false,"non_official_content_accepted":false,"raw_profile_url_accepted":false,"raw_profile_handle_accepted":false,"raw_search_query_accepted":false,"member_credentials_accepted":false,"session_cookie_accepted":false,"browser_automation_available":false,"login_automation_available":false,"profile_scraping_available":false,"company_scraping_available":false,"post_scraping_available":false,"job_scraping_available":false,"contact_extraction_available":false,"email_extraction_available":false,"message_send_authorized":false,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}],"total":0,"limit":1,"offset":0,"execution_available":false,"provider_requests_made":0,"profiles_displayed":0,"provider_content_stored":false}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"List Professional Network Specifications. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."}},"/v1/professional-network-specifications/{specification_id}":{"get":{"tags":["Professional Network"],"summary":"Get Professional Network Specification","operationId":"get_professional_network_specification_v1_professional_network_specifications__specification_id__get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"specification_id","in":"path","required":true,"schema":{"type":"string","pattern":"^pronet_[a-f0-9]{24}$","title":"Specification Id"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfessionalNetworkSpecificationOut"},"example":{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"pronet_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","selection":{"mode":"included","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"member_count":1,"member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","member_bindings":[{"id":"audmem_aaaaaaaaaaaaaaaaaaaaaaaa","source_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","review_status":"included","snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","identity_reference_present":true}]},"connection":{"connection_id":"conn_aaaaaaaaaaaaaaaaaaaaaaaa","provider_key":"linkedin-sales-navigator","manifest_version":"2026-07-14","credentials_version":1,"configured_fields":["Example configured fields","Example configured fields","Example configured fields","Example configured fields"],"status":"configured","live_verification_status":"not_run","credentials_decrypted":false,"access_token_stored":false,"member_password_stored":false,"browser_session_stored":false},"source_policy":{"provider":"linkedin_sales_navigator","display_name":"LinkedIn Sales Navigator","program":"sales_navigator_application_platform","operation":"display_services","integration_mode":"official_api_oauth2","oauth_flow":"member_authorization","required_scopes":["r_sales_nav_display"],"connector_manifest_key":"linkedin-sales-navigator","partner_approval_required":true,"new_partner_intake_available":false,"availability_observed_at":"2026-07-13","display_only":true,"provider_content_storage_authorized":false,"official_program_documentation_url":"https://example.com","official_display_documentation_url":"https://example.com","official_access_documentation_url":"https://example.com","official_api_terms_url":"https://example.com","official_user_agreement_url":"https://example.com","maximum_members":25},"display_components":["profile_summary"],"purpose":"crm_sync","policy_version":"2026-07-13","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"provider_requests_made":0,"network_requests_made":0,"browser_requests_made":0,"profiles_matched":0,"profiles_displayed":0,"provider_records_read":0,"provider_content_stored":false,"non_official_content_accepted":false,"raw_profile_url_accepted":false,"raw_profile_handle_accepted":false,"raw_search_query_accepted":false,"member_credentials_accepted":false,"session_cookie_accepted":false,"browser_automation_available":false,"login_automation_available":false,"profile_scraping_available":false,"company_scraping_available":false,"post_scraping_available":false,"job_scraping_available":false,"contact_extraction_available":false,"email_extraction_available":false,"message_send_authorized":false,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"Get Professional Network Specification. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."}},"/v1/prospect-research-specifications":{"post":{"tags":["Prospect Research"],"summary":"Create Prospect Research Specification","operationId":"create_prospect_research_specification_v1_prospect_research_specifications_post","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectResearchSpecificationCreateIn"},"example":{"key":"example-key","audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","expected_audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","selection":{"mode":"included"},"lenses":["business_priorities"],"collection_budget":{"max_provider_requests_per_member":0,"max_model_requests_per_member":1,"max_agent_tool_calls_per_member":0,"max_evidence_items_per_member":1,"max_model_input_chars_per_member":1000},"purpose":"qualification","expected_policy_version":"2026-07-15","reason":"Example value"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectResearchSpecificationOut"},"example":{"schema_version":"2026-07-15","status":"specified","availability":"contract_only","id":"prosresearch_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","selection":{"mode":"included","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"member_count":1,"member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","member_bindings":[{"id":"audmem_aaaaaaaaaaaaaaaaaaaaaaaa","source_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","review_status":"included","snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","identity_reference_present":true}]},"source_requirements":{"permitted_purpose":"qualification","credentials_in_specification_accepted":false,"public_web_allowed":false,"restricted_broker_allowed":false,"automated_scraping_allowed":false,"raw_third_party_aggregates_allowed":false},"lenses":["business_priorities"],"lens_specs":[{"lens":"business_priorities","claim_type":"Example claim type","description":"Example description","allowed_evidence_types":["audience_evidence"],"maximum_evidence_age_days":1,"minimum_evidence_items_per_claim":1,"explicit_evidence_only":true,"unsupported_behavior":"omit"}],"collection_budget":{"max_provider_requests_per_member":0,"max_model_requests_per_member":1,"max_agent_tool_calls_per_member":0,"max_evidence_items_per_member":1,"max_model_input_chars_per_member":1000,"member_count":1,"max_total_provider_requests":0,"max_total_model_requests":1,"max_total_agent_tool_calls":0,"hard_limits_required":true,"quota_reserved":false},"analysis_policy":{"source_content_classification":"untrusted_data","embedded_instruction_handling":"ignore","claim_evidence_binding":"required","unsupported_claim_handling":"omit","conflicting_evidence_handling":"retain_and_flag","model_output_validation":"required","prompt_template_version":"prospect-research-2026-07-14","model_identity_recording_required":true,"prompt_hash_recording_required":true,"source_snapshot_hash_recording_required":true,"forbidden_inferences":["creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness"],"scoring_or_ranking_allowed":false,"outreach_generation_allowed":false,"hiring_or_investing_decision_support_allowed":false},"result_contract":{"schema_version":"2026-07-15","result_shape":"member_evidence_claim_sets","member_reference_field":"audience_member_id","claim_fields":["lens"],"evidence_fields":["evidence_id"],"unsupported_lens_status":"unsupported","citations_required":true,"raw_source_payload_returned":false},"purpose":"qualification","policy_version":"2026-07-15","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"provider_requests_made":0,"model_requests_made":0,"agent_tool_calls_made":0,"network_requests_made":0,"browser_requests_made":0,"source_records_read":0,"raw_provider_records_stored":false,"raw_profile_url_accepted":false,"raw_profile_handle_accepted":false,"raw_provider_payload_accepted":false,"arbitrary_prompt_accepted":false,"custom_insight_definition_accepted":false,"source_instructions_followed":false,"third_party_scraping_available":false,"restricted_broker_content_accepted":false,"evidence_claims_created":0,"profiles_scored":0,"profiles_ranked":0,"personality_traits_inferred":0,"protected_attributes_inferred":0,"outreach_drafts_created":0,"hiring_decisions_supported":false,"investment_decisions_supported":false,"credit_decisions_supported":false,"message_send_authorized":false,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"200":{"description":"Exact replay of an immutable specification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectResearchSpecificationOut"},"example":{"schema_version":"2026-07-15","status":"specified","availability":"contract_only","id":"prosresearch_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","selection":{"mode":"included","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"member_count":1,"member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","member_bindings":[{"id":"audmem_aaaaaaaaaaaaaaaaaaaaaaaa","source_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","review_status":"included","snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","identity_reference_present":true}]},"source_requirements":{"permitted_purpose":"qualification","credentials_in_specification_accepted":false,"public_web_allowed":false,"restricted_broker_allowed":false,"automated_scraping_allowed":false,"raw_third_party_aggregates_allowed":false},"lenses":["business_priorities"],"lens_specs":[{"lens":"business_priorities","claim_type":"Example claim type","description":"Example description","allowed_evidence_types":["audience_evidence"],"maximum_evidence_age_days":1,"minimum_evidence_items_per_claim":1,"explicit_evidence_only":true,"unsupported_behavior":"omit"}],"collection_budget":{"max_provider_requests_per_member":0,"max_model_requests_per_member":1,"max_agent_tool_calls_per_member":0,"max_evidence_items_per_member":1,"max_model_input_chars_per_member":1000,"member_count":1,"max_total_provider_requests":0,"max_total_model_requests":1,"max_total_agent_tool_calls":0,"hard_limits_required":true,"quota_reserved":false},"analysis_policy":{"source_content_classification":"untrusted_data","embedded_instruction_handling":"ignore","claim_evidence_binding":"required","unsupported_claim_handling":"omit","conflicting_evidence_handling":"retain_and_flag","model_output_validation":"required","prompt_template_version":"prospect-research-2026-07-14","model_identity_recording_required":true,"prompt_hash_recording_required":true,"source_snapshot_hash_recording_required":true,"forbidden_inferences":["creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness"],"scoring_or_ranking_allowed":false,"outreach_generation_allowed":false,"hiring_or_investing_decision_support_allowed":false},"result_contract":{"schema_version":"2026-07-15","result_shape":"member_evidence_claim_sets","member_reference_field":"audience_member_id","claim_fields":["lens"],"evidence_fields":["evidence_id"],"unsupported_lens_status":"unsupported","citations_required":true,"raw_source_payload_returned":false},"purpose":"qualification","policy_version":"2026-07-15","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"provider_requests_made":0,"model_requests_made":0,"agent_tool_calls_made":0,"network_requests_made":0,"browser_requests_made":0,"source_records_read":0,"raw_provider_records_stored":false,"raw_profile_url_accepted":false,"raw_profile_handle_accepted":false,"raw_provider_payload_accepted":false,"arbitrary_prompt_accepted":false,"custom_insight_definition_accepted":false,"source_instructions_followed":false,"third_party_scraping_available":false,"restricted_broker_content_accepted":false,"evidence_claims_created":0,"profiles_scored":0,"profiles_ranked":0,"personality_traits_inferred":0,"protected_attributes_inferred":0,"outreach_drafts_created":0,"hiring_decisions_supported":false,"investment_decisions_supported":false,"credit_decisions_supported":false,"message_send_authorized":false,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"Create Prospect Research Specification. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."},"get":{"tags":["Prospect Research"],"summary":"List Prospect Research Specifications","operationId":"list_prospect_research_specifications_v1_prospect_research_specifications_get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"default":0,"title":"Offset"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectResearchSpecificationListOut"},"example":{"schema_version":"2026-07-15","availability":"contract_only","specifications":[{"schema_version":"2026-07-15","status":"specified","availability":"contract_only","id":"prosresearch_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","selection":{"mode":"included","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"member_count":1,"member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","member_bindings":[{"id":"audmem_aaaaaaaaaaaaaaaaaaaaaaaa","source_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","review_status":"included","snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","identity_reference_present":true}]},"source_requirements":{"permitted_purpose":"qualification","credentials_in_specification_accepted":false,"public_web_allowed":false,"restricted_broker_allowed":false,"automated_scraping_allowed":false,"raw_third_party_aggregates_allowed":false},"lenses":["business_priorities"],"lens_specs":[{"lens":"business_priorities","claim_type":"Example claim type","description":"Example description","allowed_evidence_types":["audience_evidence"],"maximum_evidence_age_days":1,"minimum_evidence_items_per_claim":1,"explicit_evidence_only":true,"unsupported_behavior":"omit"}],"collection_budget":{"max_provider_requests_per_member":0,"max_model_requests_per_member":1,"max_agent_tool_calls_per_member":0,"max_evidence_items_per_member":1,"max_model_input_chars_per_member":1000,"member_count":1,"max_total_provider_requests":0,"max_total_model_requests":1,"max_total_agent_tool_calls":0,"hard_limits_required":true,"quota_reserved":false},"analysis_policy":{"source_content_classification":"untrusted_data","embedded_instruction_handling":"ignore","claim_evidence_binding":"required","unsupported_claim_handling":"omit","conflicting_evidence_handling":"retain_and_flag","model_output_validation":"required","prompt_template_version":"prospect-research-2026-07-14","model_identity_recording_required":true,"prompt_hash_recording_required":true,"source_snapshot_hash_recording_required":true,"forbidden_inferences":["creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness"],"scoring_or_ranking_allowed":false,"outreach_generation_allowed":false,"hiring_or_investing_decision_support_allowed":false},"result_contract":{"schema_version":"2026-07-15","result_shape":"member_evidence_claim_sets","member_reference_field":"audience_member_id","claim_fields":["lens"],"evidence_fields":["evidence_id"],"unsupported_lens_status":"unsupported","citations_required":true,"raw_source_payload_returned":false},"purpose":"qualification","policy_version":"2026-07-15","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"provider_requests_made":0,"model_requests_made":0,"agent_tool_calls_made":0,"network_requests_made":0,"browser_requests_made":0,"source_records_read":0,"raw_provider_records_stored":false,"raw_profile_url_accepted":false,"raw_profile_handle_accepted":false,"raw_provider_payload_accepted":false,"arbitrary_prompt_accepted":false,"custom_insight_definition_accepted":false,"source_instructions_followed":false,"third_party_scraping_available":false,"restricted_broker_content_accepted":false,"evidence_claims_created":0,"profiles_scored":0,"profiles_ranked":0,"personality_traits_inferred":0,"protected_attributes_inferred":0,"outreach_drafts_created":0,"hiring_decisions_supported":false,"investment_decisions_supported":false,"credit_decisions_supported":false,"message_send_authorized":false,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}],"total":0,"limit":1,"offset":0,"execution_available":false,"provider_requests_made":0,"model_requests_made":0,"evidence_claims_created":0,"raw_provider_records_stored":false}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"List Prospect Research Specifications. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."}},"/v1/prospect-research-specifications/{specification_id}":{"get":{"tags":["Prospect Research"],"summary":"Get Prospect Research Specification","operationId":"get_prospect_research_specification_v1_prospect_research_specifications__specification_id__get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"specification_id","in":"path","required":true,"schema":{"type":"string","pattern":"^prosresearch_[a-f0-9]{24}$","title":"Specification Id"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectResearchSpecificationOut"},"example":{"schema_version":"2026-07-15","status":"specified","availability":"contract_only","id":"prosresearch_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","selection":{"mode":"included","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"member_count":1,"member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","member_bindings":[{"id":"audmem_aaaaaaaaaaaaaaaaaaaaaaaa","source_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","review_status":"included","snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","identity_reference_present":true}]},"source_requirements":{"permitted_purpose":"qualification","credentials_in_specification_accepted":false,"public_web_allowed":false,"restricted_broker_allowed":false,"automated_scraping_allowed":false,"raw_third_party_aggregates_allowed":false},"lenses":["business_priorities"],"lens_specs":[{"lens":"business_priorities","claim_type":"Example claim type","description":"Example description","allowed_evidence_types":["audience_evidence"],"maximum_evidence_age_days":1,"minimum_evidence_items_per_claim":1,"explicit_evidence_only":true,"unsupported_behavior":"omit"}],"collection_budget":{"max_provider_requests_per_member":0,"max_model_requests_per_member":1,"max_agent_tool_calls_per_member":0,"max_evidence_items_per_member":1,"max_model_input_chars_per_member":1000,"member_count":1,"max_total_provider_requests":0,"max_total_model_requests":1,"max_total_agent_tool_calls":0,"hard_limits_required":true,"quota_reserved":false},"analysis_policy":{"source_content_classification":"untrusted_data","embedded_instruction_handling":"ignore","claim_evidence_binding":"required","unsupported_claim_handling":"omit","conflicting_evidence_handling":"retain_and_flag","model_output_validation":"required","prompt_template_version":"prospect-research-2026-07-14","model_identity_recording_required":true,"prompt_hash_recording_required":true,"source_snapshot_hash_recording_required":true,"forbidden_inferences":["creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness"],"scoring_or_ranking_allowed":false,"outreach_generation_allowed":false,"hiring_or_investing_decision_support_allowed":false},"result_contract":{"schema_version":"2026-07-15","result_shape":"member_evidence_claim_sets","member_reference_field":"audience_member_id","claim_fields":["lens"],"evidence_fields":["evidence_id"],"unsupported_lens_status":"unsupported","citations_required":true,"raw_source_payload_returned":false},"purpose":"qualification","policy_version":"2026-07-15","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"provider_requests_made":0,"model_requests_made":0,"agent_tool_calls_made":0,"network_requests_made":0,"browser_requests_made":0,"source_records_read":0,"raw_provider_records_stored":false,"raw_profile_url_accepted":false,"raw_profile_handle_accepted":false,"raw_provider_payload_accepted":false,"arbitrary_prompt_accepted":false,"custom_insight_definition_accepted":false,"source_instructions_followed":false,"third_party_scraping_available":false,"restricted_broker_content_accepted":false,"evidence_claims_created":0,"profiles_scored":0,"profiles_ranked":0,"personality_traits_inferred":0,"protected_attributes_inferred":0,"outreach_drafts_created":0,"hiring_decisions_supported":false,"investment_decisions_supported":false,"credit_decisions_supported":false,"message_send_authorized":false,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"Get Prospect Research Specification. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."}},"/v1/company-dossier-specifications":{"post":{"tags":["Documents"],"summary":"Create Company Dossier Specification","operationId":"create_company_dossier_specification_v1_company_dossier_specifications_post","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyDossierSpecificationCreateIn"},"example":{"key":"example-key","target":{"domain":"Example domain"},"connection":{"connection_id":"conn_aaaaaaaaaaaaaaaaaaaaaaaa","expected_manifest_version":"2026-07-14","expected_credentials_version":1},"sections":["company_profile"],"collection_budget":{"maximum_map_requests":1,"maximum_site_pages":1,"maximum_search_requests":0,"maximum_search_results_per_query":1,"maximum_provider_credits":1,"maximum_model_requests":1,"maximum_model_input_chars":1000,"maximum_evidence_items":1,"maximum_concurrent_requests":1,"request_timeout_seconds":5,"maximum_wall_time_seconds":30},"purpose":"company_research","expected_policy_version":"2026-07-15","reason":"Example value"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyDossierSpecificationOut"},"example":{"schema_version":"2026-07-15","status":"specified","availability":"contract_only","id":"companydossier_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","target":{"domain":"Example domain","origin":"https://example.com","root_path":"/","arbitrary_url_accepted":false,"public_dns_preflight_required":true},"connection":{"connection_id":"conn_aaaaaaaaaaaaaaaaaaaaaaaa","provider_key":"firecrawl","manifest_version":"2026-07-14","credentials_version":1,"configured_fields":["api_key"],"status":"configured","live_verification_status":"not_run","credentials_decrypted":false},"sections":["company_profile"],"section_specs":[{"section":"company_profile","description":"Example description","claim_types":["Example claim types"],"maximum_evidence_age_days":1,"minimum_evidence_items_per_claim":1,"unsupported_behavior":"omit"}],"contains_personal_data":true,"collection_budget":{"maximum_map_requests":1,"maximum_site_pages":1,"maximum_search_requests":0,"maximum_search_results_per_query":1,"maximum_provider_credits":1,"maximum_model_requests":1,"maximum_model_input_chars":1000,"maximum_evidence_items":1,"maximum_concurrent_requests":1,"request_timeout_seconds":5,"maximum_wall_time_seconds":30,"maximum_total_provider_requests":2,"maximum_external_search_results":0,"provider_credit_budget_is_hard":true,"model_request_budget_is_hard":true,"global_request_semaphore_required":true,"quota_reserved":false},"provider_policy":{"provider":"firecrawl","api_version":"v2","operations":[{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0},{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0},{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0}],"query_kinds":["company_competitors"],"query_templates_platform_owned":true,"user_query_accepted":false,"user_prompt_accepted":false,"target_glob_accepted":false,"site_scope":"same_origin","include_subdomains":false,"external_links_followed_from_site":false,"returned_url_scope_validation_required":true,"globally_routable_dns_required":true,"dns_rebinding_protection_required":true,"tls_certificate_verification_required":true,"provider_default_skip_tls_overridden":true,"headers_or_cookies_forwarded_to_target":false,"browser_actions_allowed":false,"raw_html_requested":false,"screenshots_requested":false,"search_result_limit_hard":true,"retry_after_honored":true,"automatic_retry_attempts":1,"credentials_revalidated_before_each_request":true},"analysis_policy":{"source_content_classification":"untrusted_data","embedded_instruction_handling":"ignore","platform_managed_model_only":true,"caller_model_accepted":false,"source_model_binding_carried_forward":false,"model_allowlist_revalidation_required":true,"structured_outputs_required":true,"strict_json_schema_required":true,"additional_properties_allowed":false,"model_identity_recording_required":true,"prompt_template_version":"company-dossier-2026-07-14","prompt_hash_recording_required":true,"output_schema_hash_recording_required":true,"source_snapshot_hash_recording_required":true,"claim_evidence_binding":"required","unsupported_claim_handling":"omit","conflicting_evidence_handling":"retain_and_flag","model_output_validation":"required","raw_prompt_logging_allowed":false,"raw_source_logging_allowed":false,"scoring_or_ranking_allowed":false,"outreach_generation_allowed":false},"review_policy":{"initial_state":"draft_requires_human_review","allowed_decisions":["accept","accept"],"maximum_revision_rounds":3,"immutable_revision_hash_required":true,"previous_revision_hash_required":true,"reviewer_reason_required":true,"acceptance_is_outbound_authorization":false,"acceptance_is_export_authorization":false,"unlimited_revision_loop_allowed":false},"result_contract":{"schema_version":"2026-07-15","result_shape":"company_dossier_revision_proposal","dossier_fields":["Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields"],"claim_fields":["Example claim fields","Example claim fields","Example claim fields","Example claim fields","Example claim fields","Example claim fields"],"evidence_fields":["Example evidence fields","Example evidence fields","Example evidence fields","Example evidence fields","Example evidence fields"],"citations_required":true,"leadership_identity_status":"unverified_public_business_claim","contact_coordinates_returned":false,"profile_urls_returned":false,"raw_source_urls_returned":false,"raw_source_payload_returned":false,"executable_markup_returned":false,"mermaid_returned":false,"rendering_available":false},"purpose":"company_research","policy_version":"2026-07-15","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"provider_requests_made":0,"provider_credits_spent":0,"model_requests_made":0,"network_requests_made":0,"browser_requests_made":0,"map_requests_made":0,"scrape_requests_made":0,"search_requests_made":0,"pages_fetched":0,"search_results_read":0,"source_records_read":0,"source_content_stored":false,"raw_provider_payload_stored":false,"arbitrary_url_accepted":false,"arbitrary_prompt_accepted":false,"source_instructions_followed":false,"dossier_revisions_created":0,"dossier_claims_created":0,"evidence_items_created":0,"human_reviews_recorded":0,"documents_rendered":0,"exports_created":0,"contact_coordinates_created":0,"outreach_drafts_created":0,"message_send_authorized":false,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"200":{"description":"Exact replay of an immutable company-dossier specification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyDossierSpecificationOut"},"example":{"schema_version":"2026-07-15","status":"specified","availability":"contract_only","id":"companydossier_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","target":{"domain":"Example domain","origin":"https://example.com","root_path":"/","arbitrary_url_accepted":false,"public_dns_preflight_required":true},"connection":{"connection_id":"conn_aaaaaaaaaaaaaaaaaaaaaaaa","provider_key":"firecrawl","manifest_version":"2026-07-14","credentials_version":1,"configured_fields":["api_key"],"status":"configured","live_verification_status":"not_run","credentials_decrypted":false},"sections":["company_profile"],"section_specs":[{"section":"company_profile","description":"Example description","claim_types":["Example claim types"],"maximum_evidence_age_days":1,"minimum_evidence_items_per_claim":1,"unsupported_behavior":"omit"}],"contains_personal_data":true,"collection_budget":{"maximum_map_requests":1,"maximum_site_pages":1,"maximum_search_requests":0,"maximum_search_results_per_query":1,"maximum_provider_credits":1,"maximum_model_requests":1,"maximum_model_input_chars":1000,"maximum_evidence_items":1,"maximum_concurrent_requests":1,"request_timeout_seconds":5,"maximum_wall_time_seconds":30,"maximum_total_provider_requests":2,"maximum_external_search_results":0,"provider_credit_budget_is_hard":true,"model_request_budget_is_hard":true,"global_request_semaphore_required":true,"quota_reserved":false},"provider_policy":{"provider":"firecrawl","api_version":"v2","operations":[{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0},{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0},{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0}],"query_kinds":["company_competitors"],"query_templates_platform_owned":true,"user_query_accepted":false,"user_prompt_accepted":false,"target_glob_accepted":false,"site_scope":"same_origin","include_subdomains":false,"external_links_followed_from_site":false,"returned_url_scope_validation_required":true,"globally_routable_dns_required":true,"dns_rebinding_protection_required":true,"tls_certificate_verification_required":true,"provider_default_skip_tls_overridden":true,"headers_or_cookies_forwarded_to_target":false,"browser_actions_allowed":false,"raw_html_requested":false,"screenshots_requested":false,"search_result_limit_hard":true,"retry_after_honored":true,"automatic_retry_attempts":1,"credentials_revalidated_before_each_request":true},"analysis_policy":{"source_content_classification":"untrusted_data","embedded_instruction_handling":"ignore","platform_managed_model_only":true,"caller_model_accepted":false,"source_model_binding_carried_forward":false,"model_allowlist_revalidation_required":true,"structured_outputs_required":true,"strict_json_schema_required":true,"additional_properties_allowed":false,"model_identity_recording_required":true,"prompt_template_version":"company-dossier-2026-07-14","prompt_hash_recording_required":true,"output_schema_hash_recording_required":true,"source_snapshot_hash_recording_required":true,"claim_evidence_binding":"required","unsupported_claim_handling":"omit","conflicting_evidence_handling":"retain_and_flag","model_output_validation":"required","raw_prompt_logging_allowed":false,"raw_source_logging_allowed":false,"scoring_or_ranking_allowed":false,"outreach_generation_allowed":false},"review_policy":{"initial_state":"draft_requires_human_review","allowed_decisions":["accept","accept"],"maximum_revision_rounds":3,"immutable_revision_hash_required":true,"previous_revision_hash_required":true,"reviewer_reason_required":true,"acceptance_is_outbound_authorization":false,"acceptance_is_export_authorization":false,"unlimited_revision_loop_allowed":false},"result_contract":{"schema_version":"2026-07-15","result_shape":"company_dossier_revision_proposal","dossier_fields":["Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields"],"claim_fields":["Example claim fields","Example claim fields","Example claim fields","Example claim fields","Example claim fields","Example claim fields"],"evidence_fields":["Example evidence fields","Example evidence fields","Example evidence fields","Example evidence fields","Example evidence fields"],"citations_required":true,"leadership_identity_status":"unverified_public_business_claim","contact_coordinates_returned":false,"profile_urls_returned":false,"raw_source_urls_returned":false,"raw_source_payload_returned":false,"executable_markup_returned":false,"mermaid_returned":false,"rendering_available":false},"purpose":"company_research","policy_version":"2026-07-15","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"provider_requests_made":0,"provider_credits_spent":0,"model_requests_made":0,"network_requests_made":0,"browser_requests_made":0,"map_requests_made":0,"scrape_requests_made":0,"search_requests_made":0,"pages_fetched":0,"search_results_read":0,"source_records_read":0,"source_content_stored":false,"raw_provider_payload_stored":false,"arbitrary_url_accepted":false,"arbitrary_prompt_accepted":false,"source_instructions_followed":false,"dossier_revisions_created":0,"dossier_claims_created":0,"evidence_items_created":0,"human_reviews_recorded":0,"documents_rendered":0,"exports_created":0,"contact_coordinates_created":0,"outreach_drafts_created":0,"message_send_authorized":false,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"Create Company Dossier Specification. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."},"get":{"tags":["Documents"],"summary":"List Company Dossier Specifications","operationId":"list_company_dossier_specifications_v1_company_dossier_specifications_get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"default":0,"title":"Offset"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyDossierSpecificationListOut"},"example":{"schema_version":"2026-07-15","availability":"contract_only","specifications":[{"schema_version":"2026-07-15","status":"specified","availability":"contract_only","id":"companydossier_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","target":{"domain":"Example domain","origin":"https://example.com","root_path":"/","arbitrary_url_accepted":false,"public_dns_preflight_required":true},"connection":{"connection_id":"conn_aaaaaaaaaaaaaaaaaaaaaaaa","provider_key":"firecrawl","manifest_version":"2026-07-14","credentials_version":1,"configured_fields":["api_key"],"status":"configured","live_verification_status":"not_run","credentials_decrypted":false},"sections":["company_profile"],"section_specs":[{"section":"company_profile","description":"Example description","claim_types":["Example claim types"],"maximum_evidence_age_days":1,"minimum_evidence_items_per_claim":1,"unsupported_behavior":"omit"}],"contains_personal_data":true,"collection_budget":{"maximum_map_requests":1,"maximum_site_pages":1,"maximum_search_requests":0,"maximum_search_results_per_query":1,"maximum_provider_credits":1,"maximum_model_requests":1,"maximum_model_input_chars":1000,"maximum_evidence_items":1,"maximum_concurrent_requests":1,"request_timeout_seconds":5,"maximum_wall_time_seconds":30,"maximum_total_provider_requests":2,"maximum_external_search_results":0,"provider_credit_budget_is_hard":true,"model_request_budget_is_hard":true,"global_request_semaphore_required":true,"quota_reserved":false},"provider_policy":{"provider":"firecrawl","api_version":"v2","operations":[{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0},{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0},{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0}],"query_kinds":["company_competitors"],"query_templates_platform_owned":true,"user_query_accepted":false,"user_prompt_accepted":false,"target_glob_accepted":false,"site_scope":"same_origin","include_subdomains":false,"external_links_followed_from_site":false,"returned_url_scope_validation_required":true,"globally_routable_dns_required":true,"dns_rebinding_protection_required":true,"tls_certificate_verification_required":true,"provider_default_skip_tls_overridden":true,"headers_or_cookies_forwarded_to_target":false,"browser_actions_allowed":false,"raw_html_requested":false,"screenshots_requested":false,"search_result_limit_hard":true,"retry_after_honored":true,"automatic_retry_attempts":1,"credentials_revalidated_before_each_request":true},"analysis_policy":{"source_content_classification":"untrusted_data","embedded_instruction_handling":"ignore","platform_managed_model_only":true,"caller_model_accepted":false,"source_model_binding_carried_forward":false,"model_allowlist_revalidation_required":true,"structured_outputs_required":true,"strict_json_schema_required":true,"additional_properties_allowed":false,"model_identity_recording_required":true,"prompt_template_version":"company-dossier-2026-07-14","prompt_hash_recording_required":true,"output_schema_hash_recording_required":true,"source_snapshot_hash_recording_required":true,"claim_evidence_binding":"required","unsupported_claim_handling":"omit","conflicting_evidence_handling":"retain_and_flag","model_output_validation":"required","raw_prompt_logging_allowed":false,"raw_source_logging_allowed":false,"scoring_or_ranking_allowed":false,"outreach_generation_allowed":false},"review_policy":{"initial_state":"draft_requires_human_review","allowed_decisions":["accept","accept"],"maximum_revision_rounds":3,"immutable_revision_hash_required":true,"previous_revision_hash_required":true,"reviewer_reason_required":true,"acceptance_is_outbound_authorization":false,"acceptance_is_export_authorization":false,"unlimited_revision_loop_allowed":false},"result_contract":{"schema_version":"2026-07-15","result_shape":"company_dossier_revision_proposal","dossier_fields":["Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields"],"claim_fields":["Example claim fields","Example claim fields","Example claim fields","Example claim fields","Example claim fields","Example claim fields"],"evidence_fields":["Example evidence fields","Example evidence fields","Example evidence fields","Example evidence fields","Example evidence fields"],"citations_required":true,"leadership_identity_status":"unverified_public_business_claim","contact_coordinates_returned":false,"profile_urls_returned":false,"raw_source_urls_returned":false,"raw_source_payload_returned":false,"executable_markup_returned":false,"mermaid_returned":false,"rendering_available":false},"purpose":"company_research","policy_version":"2026-07-15","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"provider_requests_made":0,"provider_credits_spent":0,"model_requests_made":0,"network_requests_made":0,"browser_requests_made":0,"map_requests_made":0,"scrape_requests_made":0,"search_requests_made":0,"pages_fetched":0,"search_results_read":0,"source_records_read":0,"source_content_stored":false,"raw_provider_payload_stored":false,"arbitrary_url_accepted":false,"arbitrary_prompt_accepted":false,"source_instructions_followed":false,"dossier_revisions_created":0,"dossier_claims_created":0,"evidence_items_created":0,"human_reviews_recorded":0,"documents_rendered":0,"exports_created":0,"contact_coordinates_created":0,"outreach_drafts_created":0,"message_send_authorized":false,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}],"total":0,"limit":1,"offset":0,"execution_available":false,"provider_requests_made":0,"model_requests_made":0,"dossier_revisions_created":0}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"List Company Dossier Specifications. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."}},"/v1/company-dossier-specifications/{specification_id}":{"get":{"tags":["Documents"],"summary":"Get Company Dossier Specification","operationId":"get_company_dossier_specification_v1_company_dossier_specifications__specification_id__get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"specification_id","in":"path","required":true,"schema":{"type":"string","pattern":"^companydossier_[a-f0-9]{24}$","title":"Specification Id"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyDossierSpecificationOut"},"example":{"schema_version":"2026-07-15","status":"specified","availability":"contract_only","id":"companydossier_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","target":{"domain":"Example domain","origin":"https://example.com","root_path":"/","arbitrary_url_accepted":false,"public_dns_preflight_required":true},"connection":{"connection_id":"conn_aaaaaaaaaaaaaaaaaaaaaaaa","provider_key":"firecrawl","manifest_version":"2026-07-14","credentials_version":1,"configured_fields":["api_key"],"status":"configured","live_verification_status":"not_run","credentials_decrypted":false},"sections":["company_profile"],"section_specs":[{"section":"company_profile","description":"Example description","claim_types":["Example claim types"],"maximum_evidence_age_days":1,"minimum_evidence_items_per_claim":1,"unsupported_behavior":"omit"}],"contains_personal_data":true,"collection_budget":{"maximum_map_requests":1,"maximum_site_pages":1,"maximum_search_requests":0,"maximum_search_results_per_query":1,"maximum_provider_credits":1,"maximum_model_requests":1,"maximum_model_input_chars":1000,"maximum_evidence_items":1,"maximum_concurrent_requests":1,"request_timeout_seconds":5,"maximum_wall_time_seconds":30,"maximum_total_provider_requests":2,"maximum_external_search_results":0,"provider_credit_budget_is_hard":true,"model_request_budget_is_hard":true,"global_request_semaphore_required":true,"quota_reserved":false},"provider_policy":{"provider":"firecrawl","api_version":"v2","operations":[{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0},{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0},{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0}],"query_kinds":["company_competitors"],"query_templates_platform_owned":true,"user_query_accepted":false,"user_prompt_accepted":false,"target_glob_accepted":false,"site_scope":"same_origin","include_subdomains":false,"external_links_followed_from_site":false,"returned_url_scope_validation_required":true,"globally_routable_dns_required":true,"dns_rebinding_protection_required":true,"tls_certificate_verification_required":true,"provider_default_skip_tls_overridden":true,"headers_or_cookies_forwarded_to_target":false,"browser_actions_allowed":false,"raw_html_requested":false,"screenshots_requested":false,"search_result_limit_hard":true,"retry_after_honored":true,"automatic_retry_attempts":1,"credentials_revalidated_before_each_request":true},"analysis_policy":{"source_content_classification":"untrusted_data","embedded_instruction_handling":"ignore","platform_managed_model_only":true,"caller_model_accepted":false,"source_model_binding_carried_forward":false,"model_allowlist_revalidation_required":true,"structured_outputs_required":true,"strict_json_schema_required":true,"additional_properties_allowed":false,"model_identity_recording_required":true,"prompt_template_version":"company-dossier-2026-07-14","prompt_hash_recording_required":true,"output_schema_hash_recording_required":true,"source_snapshot_hash_recording_required":true,"claim_evidence_binding":"required","unsupported_claim_handling":"omit","conflicting_evidence_handling":"retain_and_flag","model_output_validation":"required","raw_prompt_logging_allowed":false,"raw_source_logging_allowed":false,"scoring_or_ranking_allowed":false,"outreach_generation_allowed":false},"review_policy":{"initial_state":"draft_requires_human_review","allowed_decisions":["accept","accept"],"maximum_revision_rounds":3,"immutable_revision_hash_required":true,"previous_revision_hash_required":true,"reviewer_reason_required":true,"acceptance_is_outbound_authorization":false,"acceptance_is_export_authorization":false,"unlimited_revision_loop_allowed":false},"result_contract":{"schema_version":"2026-07-15","result_shape":"company_dossier_revision_proposal","dossier_fields":["Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields"],"claim_fields":["Example claim fields","Example claim fields","Example claim fields","Example claim fields","Example claim fields","Example claim fields"],"evidence_fields":["Example evidence fields","Example evidence fields","Example evidence fields","Example evidence fields","Example evidence fields"],"citations_required":true,"leadership_identity_status":"unverified_public_business_claim","contact_coordinates_returned":false,"profile_urls_returned":false,"raw_source_urls_returned":false,"raw_source_payload_returned":false,"executable_markup_returned":false,"mermaid_returned":false,"rendering_available":false},"purpose":"company_research","policy_version":"2026-07-15","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"provider_requests_made":0,"provider_credits_spent":0,"model_requests_made":0,"network_requests_made":0,"browser_requests_made":0,"map_requests_made":0,"scrape_requests_made":0,"search_requests_made":0,"pages_fetched":0,"search_results_read":0,"source_records_read":0,"source_content_stored":false,"raw_provider_payload_stored":false,"arbitrary_url_accepted":false,"arbitrary_prompt_accepted":false,"source_instructions_followed":false,"dossier_revisions_created":0,"dossier_claims_created":0,"evidence_items_created":0,"human_reviews_recorded":0,"documents_rendered":0,"exports_created":0,"contact_coordinates_created":0,"outreach_drafts_created":0,"message_send_authorized":false,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"Get Company Dossier Specification. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."}},"/v1/outcomes":{"post":{"tags":["Outcomes"],"summary":"Create Outcome","operationId":"create_outcome_v1_outcomes_post","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutcomeCreateIn"},"example":{"source":"example_key","external_event_id":"Example value","type":"qualification_approved","occurred_at":"2026-07-16T00:00:00Z"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutcomeOut"},"example":{"id":"Example id","status":"recorded","idempotent_replay":true,"project_id":"Example project id","environment":"live","subject_kind":"prospect","prospecting_job_id":"Example prospecting job id","prospect_id":"Example prospect id","account_domain":"Example account domain","campaign_id":"Example campaign id","offer_id":"Example offer id","brand_profile_id":"Example brand profile id","audience_id":"Example audience id","playbook_job_id":"Example playbook job id","message_template_revision_id":"Example message template revision id","connector_id":"Example connector id","source":"Example source","external_event_id":"Example external event id","external_record_id":"Example external record id","type":"qualification_approved","classification":"preference","learning_candidate":true,"verification_status":"unverified","eligible_for_learning":true,"channel":"email","reason_code":"Example reason code","amount_usd_cents":0,"occurred_at":"2026-07-16T00:00:00Z","prospecting_result_hash":"Example prospecting result hash","recorded_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"200":{"description":"Exact idempotent replay of an existing outcome","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutcomeOut"},"example":{"id":"Example id","status":"recorded","idempotent_replay":true,"project_id":"Example project id","environment":"live","subject_kind":"prospect","prospecting_job_id":"Example prospecting job id","prospect_id":"Example prospect id","account_domain":"Example account domain","campaign_id":"Example campaign id","offer_id":"Example offer id","brand_profile_id":"Example brand profile id","audience_id":"Example audience id","playbook_job_id":"Example playbook job id","message_template_revision_id":"Example message template revision id","connector_id":"Example connector id","source":"Example source","external_event_id":"Example external event id","external_record_id":"Example external record id","type":"qualification_approved","classification":"preference","learning_candidate":true,"verification_status":"unverified","eligible_for_learning":true,"channel":"email","reason_code":"Example reason code","amount_usd_cents":0,"occurred_at":"2026-07-16T00:00:00Z","prospecting_result_hash":"Example prospecting result hash","recorded_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga","description":"Create Outcome. This is a ga operation scoped to the authenticated project or organization as documented by its response schema."},"get":{"tags":["Outcomes"],"summary":"List Outcomes","operationId":"list_outcomes_v1_outcomes_get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["qualification_approved","qualification_rejected","draft_approved","draft_rejected","delivered","positive_reply","negative_reply","meeting_booked","sales_qualified","opportunity_created","closed_won","closed_lost","ghosted","bounced","unsubscribed","email_not_found","provider_failed"],"type":"string"},{"type":"null"}],"title":"Type"}},{"name":"classification","in":"query","required":false,"schema":{"anyOf":[{"enum":["preference","commercial","operational"],"type":"string"},{"type":"null"}],"title":"Classification"}},{"name":"subject_kind","in":"query","required":false,"schema":{"anyOf":[{"enum":["prospect","account","campaign"],"type":"string"},{"type":"null"}],"title":"Subject Kind"}},{"name":"prospecting_job_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prospecting Job Id"}},{"name":"prospect_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prospect Id"}},{"name":"account_domain","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Domain"}},{"name":"campaign_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Campaign Id"}},{"name":"offer_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Offer Id"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutcomesResponse"},"example":{"outcomes":[{"id":"Example id","status":"recorded","idempotent_replay":true,"project_id":"Example project id","environment":"live","subject_kind":"prospect","prospecting_job_id":"Example prospecting job id","prospect_id":"Example prospect id","account_domain":"Example account domain","campaign_id":"Example campaign id","offer_id":"Example offer id","brand_profile_id":"Example brand profile id","audience_id":"Example audience id","playbook_job_id":"Example playbook job id","message_template_revision_id":"Example message template revision id","connector_id":"Example connector id","source":"Example source","external_event_id":"Example external event id","external_record_id":"Example external record id","type":"qualification_approved","classification":"preference","learning_candidate":true,"verification_status":"unverified","eligible_for_learning":true,"channel":"email","reason_code":"Example reason code","amount_usd_cents":0,"occurred_at":"2026-07-16T00:00:00Z","prospecting_result_hash":"Example prospecting result hash","recorded_at":"2026-07-16T00:00:00Z"}],"next_cursor":"Example next cursor","total":0}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga","description":"List Outcomes. This is a ga operation scoped to the authenticated project or organization as documented by its response schema."}},"/v1/outcomes/insights":{"get":{"tags":["Outcomes"],"summary":"Outcome Insights","operationId":"outcome_insights_v1_outcomes_insights_get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"group_by","in":"query","required":false,"schema":{"enum":["campaign","offer","brand_profile","audience","playbook_job","message_template_revision","type","channel","account_domain"],"type":"string","default":"campaign","title":"Group By"}},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Since"}},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Until"}},{"name":"campaign_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Campaign Id"}},{"name":"offer_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Offer Id"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutcomeInsightsResponse"},"example":{"group_by":"campaign","since":"2026-07-16T00:00:00Z","until":"2026-07-16T00:00:00Z","total_outcomes":0,"total_groups":0,"groups":[{"group":"Example group","total":0,"learning_candidates":0,"by_classification":{},"by_type":{},"positive_replies":0,"meetings_booked":0,"opportunities":0,"wins":0,"losses":0,"win_rate":0.0,"revenue_usd_cents":0}]}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"ga","description":"Outcome Insights. This is a ga operation scoped to the authenticated project or organization as documented by its response schema."}},"/v1/qualification-policies":{"post":{"tags":["Qualification Policies"],"summary":"Create Qualification Policy","operationId":"create_qualification_policy_v1_qualification_policies_post","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QualificationPolicyCreateIn"},"example":{"key":"example-key","target":{"industries":["ai_ml"],"seniorities":["c_suite"]},"dimensions":[{"dimension":"industry_match","weight_percent":0},{"dimension":"industry_match","weight_percent":0},{"dimension":"industry_match","weight_percent":0},{"dimension":"industry_match","weight_percent":0},{"dimension":"industry_match","weight_percent":0}],"expected_policy_version":"2026-07-13","reason":"Example value"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QualificationPolicyOut"},"example":{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"qualpolicy_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","policy_version":"2026-07-13","target":{"industries":["ai_ml"],"seniorities":["c_suite"]},"dimension_specs":[{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"}],"score_policy":{"minimum_score":0,"maximum_score":100,"weighted_rounding":"nearest_integer","missing_evidence_behavior":"unscored","grade_bands":[{"grade":"A","min_score":0,"max_score":0},{"grade":"A","min_score":0,"max_score":0},{"grade":"A","min_score":0,"max_score":0}]},"context_policy":{"seller_context_source":"prospecting_job_input","product_info_required_at_execution":true,"objective_required_at_execution":true,"real_prospecting_evidence_required":true},"policy_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","scoring_available":false,"scoring_authorized":false,"model_requests_made":0,"search_requests_made":0,"prospects_scored":0,"prospecting_jobs_modified":0,"audience_members_modified":0,"outreach_drafts_generated":0,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"200":{"description":"Exact replay of an immutable qualification policy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QualificationPolicyOut"},"example":{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"qualpolicy_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","policy_version":"2026-07-13","target":{"industries":["ai_ml"],"seniorities":["c_suite"]},"dimension_specs":[{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"}],"score_policy":{"minimum_score":0,"maximum_score":100,"weighted_rounding":"nearest_integer","missing_evidence_behavior":"unscored","grade_bands":[{"grade":"A","min_score":0,"max_score":0},{"grade":"A","min_score":0,"max_score":0},{"grade":"A","min_score":0,"max_score":0}]},"context_policy":{"seller_context_source":"prospecting_job_input","product_info_required_at_execution":true,"objective_required_at_execution":true,"real_prospecting_evidence_required":true},"policy_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","scoring_available":false,"scoring_authorized":false,"model_requests_made":0,"search_requests_made":0,"prospects_scored":0,"prospecting_jobs_modified":0,"audience_members_modified":0,"outreach_drafts_generated":0,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"Create Qualification Policy. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."},"get":{"tags":["Qualification Policies"],"summary":"List Qualification Policies","operationId":"list_qualification_policies_v1_qualification_policies_get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"default":0,"title":"Offset"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QualificationPolicyListOut"},"example":{"policies":[{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"qualpolicy_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","policy_version":"2026-07-13","target":{"industries":["ai_ml"],"seniorities":["c_suite"]},"dimension_specs":[{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"}],"score_policy":{"minimum_score":0,"maximum_score":100,"weighted_rounding":"nearest_integer","missing_evidence_behavior":"unscored","grade_bands":[{"grade":"A","min_score":0,"max_score":0},{"grade":"A","min_score":0,"max_score":0},{"grade":"A","min_score":0,"max_score":0}]},"context_policy":{"seller_context_source":"prospecting_job_input","product_info_required_at_execution":true,"objective_required_at_execution":true,"real_prospecting_evidence_required":true},"policy_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","scoring_available":false,"scoring_authorized":false,"model_requests_made":0,"search_requests_made":0,"prospects_scored":0,"prospecting_jobs_modified":0,"audience_members_modified":0,"outreach_drafts_generated":0,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}],"total":0,"limit":1,"offset":0,"availability":"contract_only","scoring_available":false,"model_requests_made":0,"search_requests_made":0}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"List Qualification Policies. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."}},"/v1/qualification-policies/{qualification_policy_id}":{"get":{"tags":["Qualification Policies"],"summary":"Get Qualification Policy","operationId":"get_qualification_policy_v1_qualification_policies__qualification_policy_id__get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"qualification_policy_id","in":"path","required":true,"schema":{"type":"string","pattern":"^qualpolicy_[a-f0-9]{24}$","title":"Qualification Policy Id"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QualificationPolicyOut"},"example":{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"qualpolicy_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","policy_version":"2026-07-13","target":{"industries":["ai_ml"],"seniorities":["c_suite"]},"dimension_specs":[{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"}],"score_policy":{"minimum_score":0,"maximum_score":100,"weighted_rounding":"nearest_integer","missing_evidence_behavior":"unscored","grade_bands":[{"grade":"A","min_score":0,"max_score":0},{"grade":"A","min_score":0,"max_score":0},{"grade":"A","min_score":0,"max_score":0}]},"context_policy":{"seller_context_source":"prospecting_job_input","product_info_required_at_execution":true,"objective_required_at_execution":true,"real_prospecting_evidence_required":true},"policy_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","scoring_available":false,"scoring_authorized":false,"model_requests_made":0,"search_requests_made":0,"prospects_scored":0,"prospecting_jobs_modified":0,"audience_members_modified":0,"outreach_drafts_generated":0,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"Get Qualification Policy. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."}},"/v1/site-audit-specifications":{"post":{"tags":["Site Intelligence"],"summary":"Create Site Audit Specification","operationId":"create_site_audit_specification_v1_site_audit_specifications_post","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteAuditSpecificationCreateIn"},"example":{"key":"example-key","target":{"domain":"Example domain","relationship":"owned_or_operated","authorization_attested":true},"check_profile":"aeo_site_readiness_29","expected_policy_version":"2026-07-13","reason":"Example value"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteAuditSpecificationOut"},"example":{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"siteaudit_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","target":{"domain":"Example domain","origin":"https://example.com","relationship":"owned_or_operated","authorization_attested":true,"root_path":"/"},"check_profile":"aeo_site_readiness_29","check_suite":{"profile":"aeo_site_readiness_29","profile_version":"2026-07-13","source_derived":true,"total_checks":29,"total_score_impact":201,"category_counts":{"technical":16,"structured_data":6,"ai_crawler":4,"authority":3},"checks":[{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]}]},"crawler_registry":{"version":"2026-07-13","revalidation_required_before_execution":true,"robots_standard":"RFC 9309","official_standard_url":"https://example.com","longest_match_required":true,"matching_groups_must_be_merged":true,"robots_rules_are_authorization":false,"identities":[{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false}]},"fetch_policy":{"scheme":"https","port":443,"methods":["GET"],"resources":[{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]},{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]},{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]}],"maximum_total_bytes":4718592,"request_timeout_seconds":10,"maximum_redirects":3,"redirect_scope":"same_origin","public_dns_resolution_required_before_each_request":true,"globally_routable_ip_required":true,"dns_rebinding_protection_required":true,"resolved_ip_pinning_required":true,"tls_certificate_verification_required":true,"credentials_accepted":false,"authorization_headers_sent":false,"cookies_sent":false,"javascript_execution":false,"browser_execution":false,"linked_page_fetches":false,"sub_sitemap_fetches":false,"cross_origin_redirects":false,"identifiable_user_agent_required":true},"score_policy":{"maximum_score":100,"base_score_formula":"weighted_severity_credit_percent","final_score_formula":"minimum_of_base_score_and_all_tier_caps","rounding":"nearest_tenth","severity_credit":{"passed":1.0,"notice":0.7,"warning":0.3,"error":0.0},"cap_rules":[{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5}],"grade_bands":[{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0}],"visibility_bands":[{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0}]},"interpretation_policy":{"heuristic_readiness_only":true,"proves_indexing":false,"proves_ranking":false,"proves_ai_citation":false,"proves_crawler_reachability":false,"robots_rules_are_access_authorization":false,"crawler_registry_revalidation_required":true},"policy_version":"2026-07-13","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"dns_queries_made":0,"http_requests_made":0,"html_requests_made":0,"robots_requests_made":0,"sitemap_requests_made":0,"redirects_followed":0,"bytes_received":0,"pages_fetched":0,"checks_evaluated":0,"audits_run":0,"scores_computed":0,"model_requests_made":0,"search_requests_made":0,"content_stored":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"200":{"description":"Exact replay of an immutable website audit specification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteAuditSpecificationOut"},"example":{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"siteaudit_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","target":{"domain":"Example domain","origin":"https://example.com","relationship":"owned_or_operated","authorization_attested":true,"root_path":"/"},"check_profile":"aeo_site_readiness_29","check_suite":{"profile":"aeo_site_readiness_29","profile_version":"2026-07-13","source_derived":true,"total_checks":29,"total_score_impact":201,"category_counts":{"technical":16,"structured_data":6,"ai_crawler":4,"authority":3},"checks":[{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]}]},"crawler_registry":{"version":"2026-07-13","revalidation_required_before_execution":true,"robots_standard":"RFC 9309","official_standard_url":"https://example.com","longest_match_required":true,"matching_groups_must_be_merged":true,"robots_rules_are_authorization":false,"identities":[{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false}]},"fetch_policy":{"scheme":"https","port":443,"methods":["GET"],"resources":[{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]},{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]},{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]}],"maximum_total_bytes":4718592,"request_timeout_seconds":10,"maximum_redirects":3,"redirect_scope":"same_origin","public_dns_resolution_required_before_each_request":true,"globally_routable_ip_required":true,"dns_rebinding_protection_required":true,"resolved_ip_pinning_required":true,"tls_certificate_verification_required":true,"credentials_accepted":false,"authorization_headers_sent":false,"cookies_sent":false,"javascript_execution":false,"browser_execution":false,"linked_page_fetches":false,"sub_sitemap_fetches":false,"cross_origin_redirects":false,"identifiable_user_agent_required":true},"score_policy":{"maximum_score":100,"base_score_formula":"weighted_severity_credit_percent","final_score_formula":"minimum_of_base_score_and_all_tier_caps","rounding":"nearest_tenth","severity_credit":{"passed":1.0,"notice":0.7,"warning":0.3,"error":0.0},"cap_rules":[{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5}],"grade_bands":[{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0}],"visibility_bands":[{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0}]},"interpretation_policy":{"heuristic_readiness_only":true,"proves_indexing":false,"proves_ranking":false,"proves_ai_citation":false,"proves_crawler_reachability":false,"robots_rules_are_access_authorization":false,"crawler_registry_revalidation_required":true},"policy_version":"2026-07-13","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"dns_queries_made":0,"http_requests_made":0,"html_requests_made":0,"robots_requests_made":0,"sitemap_requests_made":0,"redirects_followed":0,"bytes_received":0,"pages_fetched":0,"checks_evaluated":0,"audits_run":0,"scores_computed":0,"model_requests_made":0,"search_requests_made":0,"content_stored":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"Create Site Audit Specification. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."},"get":{"tags":["Site Intelligence"],"summary":"List Site Audit Specifications","operationId":"list_site_audit_specifications_v1_site_audit_specifications_get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"default":0,"title":"Offset"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteAuditSpecificationListOut"},"example":{"specifications":[{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"siteaudit_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","target":{"domain":"Example domain","origin":"https://example.com","relationship":"owned_or_operated","authorization_attested":true,"root_path":"/"},"check_profile":"aeo_site_readiness_29","check_suite":{"profile":"aeo_site_readiness_29","profile_version":"2026-07-13","source_derived":true,"total_checks":29,"total_score_impact":201,"category_counts":{"technical":16,"structured_data":6,"ai_crawler":4,"authority":3},"checks":[{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]}]},"crawler_registry":{"version":"2026-07-13","revalidation_required_before_execution":true,"robots_standard":"RFC 9309","official_standard_url":"https://example.com","longest_match_required":true,"matching_groups_must_be_merged":true,"robots_rules_are_authorization":false,"identities":[{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false}]},"fetch_policy":{"scheme":"https","port":443,"methods":["GET"],"resources":[{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]},{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]},{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]}],"maximum_total_bytes":4718592,"request_timeout_seconds":10,"maximum_redirects":3,"redirect_scope":"same_origin","public_dns_resolution_required_before_each_request":true,"globally_routable_ip_required":true,"dns_rebinding_protection_required":true,"resolved_ip_pinning_required":true,"tls_certificate_verification_required":true,"credentials_accepted":false,"authorization_headers_sent":false,"cookies_sent":false,"javascript_execution":false,"browser_execution":false,"linked_page_fetches":false,"sub_sitemap_fetches":false,"cross_origin_redirects":false,"identifiable_user_agent_required":true},"score_policy":{"maximum_score":100,"base_score_formula":"weighted_severity_credit_percent","final_score_formula":"minimum_of_base_score_and_all_tier_caps","rounding":"nearest_tenth","severity_credit":{"passed":1.0,"notice":0.7,"warning":0.3,"error":0.0},"cap_rules":[{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5}],"grade_bands":[{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0}],"visibility_bands":[{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0}]},"interpretation_policy":{"heuristic_readiness_only":true,"proves_indexing":false,"proves_ranking":false,"proves_ai_citation":false,"proves_crawler_reachability":false,"robots_rules_are_access_authorization":false,"crawler_registry_revalidation_required":true},"policy_version":"2026-07-13","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"dns_queries_made":0,"http_requests_made":0,"html_requests_made":0,"robots_requests_made":0,"sitemap_requests_made":0,"redirects_followed":0,"bytes_received":0,"pages_fetched":0,"checks_evaluated":0,"audits_run":0,"scores_computed":0,"model_requests_made":0,"search_requests_made":0,"content_stored":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}],"total":0,"limit":1,"offset":0,"availability":"contract_only","execution_available":false,"http_requests_made":0,"audits_run":0}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"List Site Audit Specifications. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."}},"/v1/site-audit-specifications/{specification_id}":{"get":{"tags":["Site Intelligence"],"summary":"Get Site Audit Specification","operationId":"get_site_audit_specification_v1_site_audit_specifications__specification_id__get","security":[{"ProjectBearerAuth":[]}],"parameters":[{"name":"specification_id","in":"path","required":true,"schema":{"type":"string","pattern":"^siteaudit_[a-f0-9]{24}$","title":"Specification Id"}},{"name":"X-Request-ID","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},{"type":"null"}],"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response.","title":"X-Request-Id"},"description":"Optional caller correlation ID: 1-128 ASCII letters, digits, `.`, `_`, `:`, or `-`, beginning with a letter or digit. Echoed in the response."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteAuditSpecificationOut"},"example":{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"siteaudit_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","target":{"domain":"Example domain","origin":"https://example.com","relationship":"owned_or_operated","authorization_attested":true,"root_path":"/"},"check_profile":"aeo_site_readiness_29","check_suite":{"profile":"aeo_site_readiness_29","profile_version":"2026-07-13","source_derived":true,"total_checks":29,"total_score_impact":201,"category_counts":{"technical":16,"structured_data":6,"ai_crawler":4,"authority":3},"checks":[{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]}]},"crawler_registry":{"version":"2026-07-13","revalidation_required_before_execution":true,"robots_standard":"RFC 9309","official_standard_url":"https://example.com","longest_match_required":true,"matching_groups_must_be_merged":true,"robots_rules_are_authorization":false,"identities":[{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false}]},"fetch_policy":{"scheme":"https","port":443,"methods":["GET"],"resources":[{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]},{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]},{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]}],"maximum_total_bytes":4718592,"request_timeout_seconds":10,"maximum_redirects":3,"redirect_scope":"same_origin","public_dns_resolution_required_before_each_request":true,"globally_routable_ip_required":true,"dns_rebinding_protection_required":true,"resolved_ip_pinning_required":true,"tls_certificate_verification_required":true,"credentials_accepted":false,"authorization_headers_sent":false,"cookies_sent":false,"javascript_execution":false,"browser_execution":false,"linked_page_fetches":false,"sub_sitemap_fetches":false,"cross_origin_redirects":false,"identifiable_user_agent_required":true},"score_policy":{"maximum_score":100,"base_score_formula":"weighted_severity_credit_percent","final_score_formula":"minimum_of_base_score_and_all_tier_caps","rounding":"nearest_tenth","severity_credit":{"passed":1.0,"notice":0.7,"warning":0.3,"error":0.0},"cap_rules":[{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5}],"grade_bands":[{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0}],"visibility_bands":[{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0}]},"interpretation_policy":{"heuristic_readiness_only":true,"proves_indexing":false,"proves_ranking":false,"proves_ai_citation":false,"proves_crawler_reachability":false,"robots_rules_are_access_authorization":false,"crawler_registry_revalidation_required":true},"policy_version":"2026-07-13","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"dns_queries_made":0,"http_requests_made":0,"html_requests_made":0,"robots_requests_made":0,"sitemap_requests_made":0,"redirects_followed":0,"bytes_received":0,"pages_fetched":0,"checks_evaluated":0,"audits_run":0,"scores_computed":0,"model_requests_made":0,"search_requests_made":0,"content_stored":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}}},"headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}}},"400":{"description":"The request cannot be accepted.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"The supplied pagination cursor is malformed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_mismatch":{"summary":"brand_profile_mismatch","value":{"error":{"code":"brand_profile_mismatch","message":"The supplied brand profile ID and key identify different profiles.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing, invalid, revoked, or expired.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"The request has no Bearer API key.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"The API key is invalid or has been revoked.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"expired_api_key":{"summary":"expired_api_key","value":{"error":{"code":"expired_api_key","message":"The API key has expired.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The organization does not have enough prepaid credits to start the run.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"No spendable prepaid credit remains, or a completed job's actual charge exceeded the remaining balance.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated API key cannot perform this action.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"forbidden":{"summary":"forbidden","value":{"error":{"code":"forbidden","message":"The authenticated caller is not allowed to perform this action.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"project_archived":{"summary":"project_archived","value":{"error":{"code":"project_archived","message":"The API key belongs to an archived project.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"capability_disabled":{"summary":"capability_disabled","value":{"error":{"code":"capability_disabled","message":"The requested capability is not enabled for the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource or retained result was not found in this project.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":"not_found","message":"The requested resource does not exist in the API key's project scope.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"result_unavailable":{"summary":"result_unavailable","value":{"error":{"code":"result_unavailable","message":"The requested audience result is no longer available.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_found":{"summary":"brand_profile_not_found","value":{"error":{"code":"brand_profile_not_found","message":"The selected brand profile does not exist in the organization.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The owned job has passed its retention window.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"job_expired":{"summary":"job_expired","value":{"error":{"code":"job_expired","message":"The job and its result have passed the 30-day retention window.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current resource state.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"not_ready":{"summary":"not_ready","value":{"error":{"code":"not_ready","message":"The asynchronous audience job has not completed yet.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":"idempotency_key_reused","message":"The idempotency key was already used with different request input.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":"idempotency_in_progress","message":"Another matching request with the same idempotency key is still being processed.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"campaign_archived":{"summary":"campaign_archived","value":{"error":{"code":"campaign_archived","message":"The campaign is archived and cannot run another cycle.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"cycle_in_progress":{"summary":"cycle_in_progress","value":{"error":{"code":"cycle_in_progress","message":"A campaign cycle is already queued or running.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_archived":{"summary":"brand_profile_archived","value":{"error":{"code":"brand_profile_archived","message":"The selected brand profile is archived.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"brand_profile_not_ready":{"summary":"brand_profile_not_ready","value":{"error":{"code":"brand_profile_not_ready","message":"The selected brand profile is not ready for Playbooks.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"missing_default_brand_profile":{"summary":"missing_default_brand_profile","value":{"error":{"code":"missing_default_brand_profile","message":"No usable default brand profile is configured.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_result_unavailable":{"summary":"audiences_result_unavailable","value":{"error":{"code":"audiences_result_unavailable","message":"The audiences backend cannot currently provide the completed result.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body or parameters failed validation.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":"invalid_request","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A rate limit, usage quota, or hard budget rejected the request. Only `rate_limit_exceeded` is transient.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}},"Retry-After":{"description":"Present only for `rate_limit_exceeded`; wait this many seconds before retrying.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"The request rate is temporarily too high.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"quota_exceeded":{"summary":"quota_exceeded","value":{"error":{"code":"quota_exceeded","message":"A project, key, or organization usage quota has been exhausted.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"budget_exceeded":{"summary":"budget_exceeded","value":{"error":{"code":"budget_exceeded","message":"A hard monthly cost budget has been reached.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The platform encountered an unexpected error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"The platform encountered an unexpected error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream audiences service returned an invalid response or error.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_error":{"summary":"audiences_backend_error","value":{"error":{"code":"audiences_backend_error","message":"The audiences backend returned an error.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}},"audiences_backend_invalid_response":{"summary":"audiences_backend_invalid_response","value":{"error":{"code":"audiences_backend_invalid_response","message":"The audiences backend returned an invalid response.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"An upstream audiences service is temporarily unavailable.","headers":{"X-Request-ID":{"description":"Request correlation ID selected or generated by the platform.","schema":{"type":"string","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]}},"RateLimit-Limit":{"description":"Maximum authenticated requests allowed in the current 60-second API-key window. Present after successful authentication.","schema":{"type":"integer","minimum":1,"examples":[120]}},"RateLimit-Remaining":{"description":"Authenticated requests remaining in the current API-key window.","schema":{"type":"integer","minimum":0,"examples":[119]}},"RateLimit-Reset":{"description":"Whole seconds until the current API-key rate window resets.","schema":{"type":"integer","minimum":1,"examples":[60]}}},"content":{"application/json":{"examples":{"audiences_backend_unavailable":{"summary":"audiences_backend_unavailable","value":{"error":{"code":"audiences_backend_unavailable","message":"The audiences backend is unavailable.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872","docs_url":"https://api.blackpearl.com/docs/errors"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-stability":"preview","description":"Get Site Audit Specification. This is a preview operation scoped to the authenticated project or organization as documented by its response schema."}}},"components":{"schemas":{"AccountContact":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Contact full name.","examples":["Taylor Callahan"]},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Contact job title.","examples":["VP Marketing"]},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Business email when the provider supplies one.","examples":["tcallahan@hubspot.com"]},"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linkedin Url","description":"LinkedIn profile URL.","examples":[null]}},"type":"object","title":"AccountContact","description":"A named contact surfaced with the account record.","examples":[{}]},"AccountCoordinationAssessmentCreateIn":{"properties":{"key":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","title":"Key","description":"The key value for this accountcoordinationassessmentcreatein.","examples":["example-key"]},"audience_id":{"type":"string","pattern":"^audience_[a-f0-9]{24}$","title":"Audience Id","description":"The audience id value for this accountcoordinationassessmentcreatein.","examples":["audience_aaaaaaaaaaaaaaaaaaaaaaaa"]},"expected_audience_result_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Expected Audience Result Hash","description":"The expected audience result hash value for this accountcoordinationassessmentcreatein.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"company_domain":{"type":"string","maxLength":253,"minLength":3,"title":"Company Domain","description":"The company domain value for this accountcoordinationassessmentcreatein.","examples":["Example company domain"]},"expected_policy_version":{"$ref":"#/components/schemas/AccountCoordinationPolicyVersion","description":"The expected policy version value for this accountcoordinationassessmentcreatein.","examples":["2026-07-13"]},"reason":{"type":"string","maxLength":500,"minLength":3,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"Reason","description":"The reason value for this accountcoordinationassessmentcreatein.","examples":["Example value"]}},"additionalProperties":false,"type":"object","required":["key","audience_id","expected_audience_result_hash","company_domain","expected_policy_version","reason"],"title":"AccountCoordinationAssessmentCreateIn","description":"Request one immutable assessment over gateway-derived account evidence.","examples":[{"key":"example-key","audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","expected_audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","company_domain":"Example company domain","expected_policy_version":"2026-07-13","reason":"Example value"}]},"AccountCoordinationAssessmentOut":{"properties":{"schema_version":{"$ref":"#/components/schemas/AccountCoordinationSchemaVersion","description":"The schema version value for this accountcoordinationassessmentout.","examples":["2026-07-13"]},"status":{"type":"string","const":"assessed","title":"Status","description":"The status value for this accountcoordinationassessmentout."},"id":{"type":"string","pattern":"^acctcoord_[a-f0-9]{24}$","title":"Id","description":"The id value for this accountcoordinationassessmentout.","examples":["acctcoord_aaaaaaaaaaaaaaaaaaaaaaaa"]},"idempotent_replay":{"type":"boolean","title":"Idempotent Replay","description":"The idempotent replay value for this accountcoordinationassessmentout.","examples":[true]},"key":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","title":"Key","description":"The key value for this accountcoordinationassessmentout.","examples":["example-key"]},"project_id":{"type":"string","pattern":"^proj_[a-f0-9]{24}$","title":"Project Id","description":"The project id value for this accountcoordinationassessmentout.","examples":["proj_aaaaaaaaaaaaaaaaaaaaaaaa"]},"environment":{"type":"string","enum":["live","test"],"title":"Environment","description":"The environment value for this accountcoordinationassessmentout.","examples":["live"]},"policy_version":{"$ref":"#/components/schemas/AccountCoordinationPolicyVersion","description":"The policy version value for this accountcoordinationassessmentout.","examples":["2026-07-13"]},"evidence":{"$ref":"#/components/schemas/AccountCoordinationEvidence","description":"The evidence value for this accountcoordinationassessmentout.","examples":[{"audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","company_domain":"Example company domain","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"outcome_ids":["outcome_aaaaaaaaaaaaaaaaaaaaaaaa"],"cutoff":"2026-07-16T00:00:00Z","member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","outcome_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","unverified_outcome_count":0}]},"state":{"$ref":"#/components/schemas/AccountCoordinationState","description":"The state value for this accountcoordinationassessmentout.","examples":["complete"]},"disposition":{"$ref":"#/components/schemas/AccountCoordinationDisposition","description":"The disposition value for this accountcoordinationassessmentout.","examples":["not_evaluated"]},"flags":{"items":{"$ref":"#/components/schemas/AccountCoordinationFlag"},"type":"array","maxItems":9,"title":"Flags","description":"The flags value for this accountcoordinationassessmentout.","examples":[["account_converted"]]},"modifications":{"$ref":"#/components/schemas/AccountCoordinationModifications","description":"The modifications value for this accountcoordinationassessmentout.","examples":[{"cadence_class":"standard","max_contacts":1,"window_days":1,"retry_after":"2026-07-16T00:00:00Z"}]},"assessment_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Assessment Hash","description":"The assessment hash value for this accountcoordinationassessmentout.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"outbound_authorized":{"type":"boolean","const":false,"title":"Outbound Authorized","description":"The outbound authorized value for this accountcoordinationassessmentout."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"The created at value for this accountcoordinationassessmentout.","examples":["2026-07-16T00:00:00Z"]}},"additionalProperties":false,"type":"object","required":["schema_version","status","id","idempotent_replay","key","project_id","environment","policy_version","evidence","state","disposition","flags","modifications","assessment_hash","outbound_authorized","created_at"],"title":"AccountCoordinationAssessmentOut","description":"Persisted data-only assessment; it never authorizes an outbound effect.","examples":[{"schema_version":"2026-07-13","status":"assessed","id":"acctcoord_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","policy_version":"2026-07-13","evidence":{"audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","company_domain":"Example company domain","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"outcome_ids":["outcome_aaaaaaaaaaaaaaaaaaaaaaaa"],"cutoff":"2026-07-16T00:00:00Z","member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","outcome_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","unverified_outcome_count":0},"state":"complete","disposition":"not_evaluated","flags":["account_converted"],"modifications":{"cadence_class":"standard","max_contacts":1,"window_days":1,"retry_after":"2026-07-16T00:00:00Z"},"assessment_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","outbound_authorized":false,"created_at":"2026-07-16T00:00:00Z"}]},"AccountCoordinationCadenceClass":{"type":"string","enum":["standard","warm_intro","reengagement","referral"],"title":"AccountCoordinationCadenceClass","description":"Structured accountcoordinationcadenceclass data exposed by the public API.","examples":["standard"]},"AccountCoordinationDisposition":{"type":"string","enum":["not_evaluated","clear","modify","delay","block"],"title":"AccountCoordinationDisposition","description":"Structured accountcoordinationdisposition data exposed by the public API.","examples":["not_evaluated"]},"AccountCoordinationEvidence":{"properties":{"audience_id":{"type":"string","pattern":"^audience_[a-f0-9]{24}$","title":"Audience Id","description":"The audience id value for this accountcoordinationevidence.","examples":["audience_aaaaaaaaaaaaaaaaaaaaaaaa"]},"audience_result_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Audience Result Hash","description":"The audience result hash value for this accountcoordinationevidence.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"company_domain":{"type":"string","maxLength":253,"minLength":3,"title":"Company Domain","description":"The company domain value for this accountcoordinationevidence.","examples":["Example company domain"]},"member_ids":{"items":{"type":"string","pattern":"^audmem_[a-f0-9]{24}$"},"type":"array","maxItems":100,"title":"Member Ids","description":"The member ids value for this accountcoordinationevidence.","examples":[["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"]]},"outcome_ids":{"items":{"type":"string","pattern":"^outcome_[a-f0-9]{24}$"},"type":"array","maxItems":500,"title":"Outcome Ids","description":"The outcome ids value for this accountcoordinationevidence.","examples":[["outcome_aaaaaaaaaaaaaaaaaaaaaaaa"]]},"cutoff":{"type":"string","format":"date-time","title":"Cutoff","description":"The cutoff value for this accountcoordinationevidence.","examples":["2026-07-16T00:00:00Z"]},"member_snapshot_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Member Snapshot Hash","description":"The member snapshot hash value for this accountcoordinationevidence.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"outcome_snapshot_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Outcome Snapshot Hash","description":"The outcome snapshot hash value for this accountcoordinationevidence.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"unverified_outcome_count":{"type":"integer","minimum":0.0,"title":"Unverified Outcome Count","description":"The unverified outcome count value for this accountcoordinationevidence.","examples":[0]}},"additionalProperties":false,"type":"object","required":["audience_id","audience_result_hash","company_domain","member_ids","outcome_ids","cutoff","member_snapshot_hash","outcome_snapshot_hash","unverified_outcome_count"],"title":"AccountCoordinationEvidence","description":"Structured accountcoordinationevidence data exposed by the public API.","examples":[{"audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","company_domain":"Example company domain","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"outcome_ids":["outcome_aaaaaaaaaaaaaaaaaaaaaaaa"],"cutoff":"2026-07-16T00:00:00Z","member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","outcome_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","unverified_outcome_count":0}]},"AccountCoordinationFlag":{"type":"string","enum":["account_converted","negative_account_signal","carpet_bomb_risk","advanced_account_new_contact","previous_relationship","pending_referral","conflicting_signals","negative_company_event","stale_evidence"],"title":"AccountCoordinationFlag","description":"Structured accountcoordinationflag data exposed by the public API.","examples":["account_converted"]},"AccountCoordinationModifications":{"properties":{"cadence_class":{"$ref":"#/components/schemas/AccountCoordinationCadenceClass","description":"The cadence class value for this accountcoordinationmodifications.","examples":["standard"]},"max_contacts":{"type":"integer","maximum":10.0,"minimum":1.0,"title":"Max Contacts","description":"The max contacts value for this accountcoordinationmodifications.","examples":[1]},"window_days":{"type":"integer","maximum":30.0,"minimum":1.0,"title":"Window Days","description":"The window days value for this accountcoordinationmodifications.","examples":[1]},"retry_after":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Retry After","description":"The retry after value for this accountcoordinationmodifications.","examples":["2026-07-16T00:00:00Z"]}},"additionalProperties":false,"type":"object","required":["cadence_class","max_contacts","window_days","retry_after"],"title":"AccountCoordinationModifications","description":"Structured accountcoordinationmodifications data exposed by the public API.","examples":[{"cadence_class":"standard","max_contacts":1,"window_days":1,"retry_after":"2026-07-16T00:00:00Z"}]},"AccountCoordinationPolicyVersion":{"type":"string","enum":["2026-07-13"],"title":"AccountCoordinationPolicyVersion","description":"Readable/replayable policies; append versions, never replace them.","examples":["2026-07-13"]},"AccountCoordinationSchemaVersion":{"type":"string","enum":["2026-07-13"],"title":"AccountCoordinationSchemaVersion","description":"Readable historical response schemas; append versions, never replace them.","examples":["2026-07-13"]},"AccountCoordinationState":{"type":"string","enum":["complete","insufficient_evidence"],"title":"AccountCoordinationState","description":"Structured accountcoordinationstate data exposed by the public API.","examples":["complete"]},"AccountDigital":{"properties":{"about_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"About Url","description":"About page URL.","examples":["https://www.hubspot.com/our-story"]},"blog_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Blog Url","description":"Blog URL; null when no blog.","examples":["https://blog.hubspot.com"]},"careers_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Careers Url","description":"Careers page URL.","examples":["https://www.hubspot.com/careers"]},"pricing_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pricing Url","description":"Pricing page URL.","examples":["https://www.hubspot.com/pricing"]},"contact_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact Url","description":"Contact page URL.","examples":["https://www.hubspot.com/company/contact"]},"product_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Product Url","description":"Product page URL.","examples":["https://www.hubspot.com/products"]},"social_links":{"items":{"type":"string"},"type":"array","title":"Social Links","description":"Social profile URLs.","examples":[["https://www.facebook.com/hubspot"]]},"third_party_integrations":{"items":{"type":"string"},"type":"array","title":"Third Party Integrations","description":"Integrations the site advertises.","examples":[["Zapier","Salesforce"]]},"languages_supported":{"items":{"type":"string"},"type":"array","title":"Languages Supported","description":"Site language codes.","examples":[["en","de"]]},"customer_support_channels":{"items":{"type":"string"},"type":"array","title":"Customer Support Channels","description":"Support channels offered.","examples":[["chat","email","phone"]]},"detected_tech":{"items":{"type":"string"},"type":"array","title":"Detected Tech","description":"Technologies detected on the website.","examples":[["HubSpot","Google Analytics"]]},"has_app":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has App","description":"Has a mobile/desktop app.","examples":[true]},"has_blog":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Blog","description":"Publishes a blog.","examples":[true]},"has_press":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Press","description":"Has a press/newsroom page.","examples":[true]},"api_availability":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Api Availability","description":"Advertises a public API.","examples":[true]},"offers_free_trial":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Offers Free Trial","description":"Offers a free trial.","examples":[true]},"offers_newsletter":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Offers Newsletter","description":"Offers a newsletter.","examples":[true]},"is_ecommerce":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Ecommerce","description":"Runs a storefront.","examples":[false]},"subscriptions":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Subscriptions","description":"Sells subscriptions.","examples":[true]}},"type":"object","title":"AccountDigital","description":"The company's web presence and stack signals.","examples":[{}]},"AccountIdentity":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Company display name.","examples":["HubSpot"]},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain","description":"Primary bare domain.","examples":["hubspot.com"]},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"Canonical website URL.","examples":["https://hubspot.com"]},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary","description":"One-paragraph business summary.","examples":["HubSpot is an AI-powered customer platform..."]},"mission_statement":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mission Statement","description":"Stated mission; null when not published.","examples":["To help businesses grow better."]},"business_history":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Business History","description":"Short company history; null when unknown.","examples":["Founded as a CRM and marketing automation pioneer."]},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry","description":"Primary industry label.","examples":["Software"]},"business_structure":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Business Structure","description":"Legal/organizational structure when detectable.","examples":["corporation"]},"founding_year":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Founding Year","description":"Founding year as published.","examples":["2006"]},"founders":{"items":{"type":"string"},"type":"array","title":"Founders","description":"Founder names when published.","examples":[["Brian Halligan","Dharmesh Shah"]]},"values":{"items":{"type":"string"},"type":"array","title":"Values","description":"Stated company values.","examples":[["innovation","customer success"]]},"adjectives":{"items":{"type":"string"},"type":"array","title":"Adjectives","description":"Adjectives the company uses to describe itself.","examples":[["AI-powered","integrated"]]}},"type":"object","title":"AccountIdentity","description":"Who the company is.","examples":[{}]},"AccountMarket":{"properties":{"b2b":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"B2B","description":"Sells to businesses.","examples":[true]},"b2c":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"B2C","description":"Sells to consumers.","examples":[false]},"product_company":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Product Company","description":"Sells products.","examples":[true]},"service_company":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Service Company","description":"Sells services.","examples":[true]},"target_customer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Customer","description":"Described target customer.","examples":["Businesses looking for integrated marketing, sales and service."]},"target_customer_industries":{"items":{"type":"string"},"type":"array","title":"Target Customer Industries","description":"Industries the company targets.","examples":[["Technology","Marketing"]]},"competitors_mentioned":{"items":{"type":"string"},"type":"array","title":"Competitors Mentioned","description":"Competitors named on the site.","examples":[[]]},"products":{"items":{"$ref":"#/components/schemas/AccountOffering"},"type":"array","title":"Products","description":"Products offered.","examples":[[{}]]},"services":{"items":{"$ref":"#/components/schemas/AccountOffering"},"type":"array","title":"Services","description":"Services offered.","examples":[[{}]]},"customer_companies":{"items":{"type":"string"},"type":"array","title":"Customer Companies","description":"Customer logos/companies listed.","examples":[[]]},"testimonials_present":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Testimonials Present","description":"Whether testimonials are published.","examples":[false]}},"type":"object","title":"AccountMarket","description":"Who the company sells to and against.","examples":[{}]},"AccountOffering":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Offering name.","examples":["Marketing Hub"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Offering description.","examples":["Free CRM platform to manage contacts."]},"price":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Price","description":"Published price text; null when absent.","examples":[null]},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"Price currency when published.","examples":[null]}},"type":"object","title":"AccountOffering","description":"A product or service the company sells.","examples":[{}]},"AccountResearchResult":{"properties":{"schema_version":{"type":"string","title":"Schema Version","description":"Result schema version.","default":"2026-07-17","examples":["2026-07-17"]},"domain":{"type":"string","title":"Domain","description":"The researched bare domain.","examples":["hubspot.com"]},"retrieved_at":{"type":"string","title":"Retrieved At","description":"When the record was retrieved (UTC ISO 8601).","examples":["2026-07-17T12:00:00Z"]},"identity":{"$ref":"#/components/schemas/AccountIdentity","description":"The identity value for this accountresearchresult.","examples":[{}]},"scale":{"$ref":"#/components/schemas/AccountScale","description":"Company size and location.","examples":[{}]},"market":{"$ref":"#/components/schemas/AccountMarket","description":"Target market, offerings and competitors.","examples":[{}]},"digital":{"$ref":"#/components/schemas/AccountDigital","description":"Web presence, stack and commerce signals.","examples":[{}]},"signals":{"$ref":"#/components/schemas/AccountSignals","description":"Qualification and messaging signals.","examples":[{}]},"contacts":{"items":{"$ref":"#/components/schemas/AccountContact"},"type":"array","title":"Contacts","description":"Named contacts the provider surfaced (may be empty).","examples":[[{}]]},"similar_companies":{"items":{"$ref":"#/components/schemas/SimilarCompany"},"type":"array","title":"Similar Companies","description":"Lookalike companies from the similarity index; populated when the lookup requests include_similar.","examples":[[{"domain":"salesloft.com"}]]},"analyzed":{"type":"boolean","title":"Analyzed","description":"True when this lookup analyzed the website on demand because no record existed yet.","default":false,"examples":[false]},"provenance":{"additionalProperties":{"type":"string"},"type":"object","title":"Provenance","description":"Backend attribution: provider and backend identifiers.","examples":[{"backend":"bebop.data","provider":"bebop"}]}},"type":"object","required":["domain","retrieved_at","identity","scale","market","digital","signals"],"title":"AccountResearchResult","description":"Structured account research for one company domain.","examples":[{"domain":"hubspot.com","retrieved_at":"2026-07-17T12:00:00Z","identity":{},"scale":{},"market":{},"digital":{},"signals":{}}]},"AccountScale":{"properties":{"employees":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Employees","description":"Employee count when published.","examples":[4000]},"offices":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Offices","description":"Number of offices when published.","examples":[10]},"users_mentioned":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Users Mentioned","description":"Customer/user count the site claims.","examples":[248000]},"revenue":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revenue","description":"Published revenue figure; null when not disclosed.","examples":[null]},"total_addressable_market":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Total Addressable Market","description":"Published TAM claim; null when absent.","examples":[null]},"primary_country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Country","description":"Primary country code.","examples":["US"]},"primary_city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary City","description":"Primary city when published.","examples":[null]}},"type":"object","title":"AccountScale","description":"How big the company is.","examples":[{}]},"AccountSignals":{"properties":{"ai_ml_initiatives":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Ai Ml Initiatives","description":"Mentions AI/ML initiatives.","examples":[true]},"blockchain_initiatives":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Blockchain Initiatives","description":"Mentions blockchain initiatives.","examples":[false]},"disruptive":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Disruptive","description":"Positions itself as disruptive.","examples":[true]},"ipo":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Ipo","description":"Signals of being publicly listed.","examples":[false]},"awards_listed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Awards Listed","description":"Lists awards.","examples":[true]},"award_providers":{"items":{"type":"string"},"type":"array","title":"Award Providers","description":"Who granted listed awards.","examples":[["G2"]]},"compliance_certifications":{"items":{"type":"string"},"type":"array","title":"Compliance Certifications","description":"Compliance certifications advertised.","examples":[[]]},"csr_initiatives":{"items":{"type":"string"},"type":"array","title":"Csr Initiatives","description":"CSR initiatives listed.","examples":[[]]},"diversity_inclusion_mentions":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Diversity Inclusion Mentions","description":"Mentions diversity & inclusion.","examples":[true]},"environmental_conscious":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Environmental Conscious","description":"Environmental positioning.","examples":[false]},"has_us_presence":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Us Presence","description":"Signals of a US presence.","examples":[true]},"patents_or_ip":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Patents Or Ip","description":"Mentions patents or IP.","examples":[false]},"job_listings":{"items":{"type":"string"},"type":"array","title":"Job Listings","description":"Open roles the site lists.","examples":[[]]}},"type":"object","title":"AccountSignals","description":"Qualitative signals useful for qualification and messaging.","examples":[{}]},"ApprovalArtifactOut":{"properties":{"artifact_kind":{"type":"string","const":"message","title":"Artifact Kind","description":"The artifact kind value for this approvalartifactout."},"artifact_id":{"type":"string","pattern":"^msgart_[a-f0-9]{64}$","title":"Artifact Id","description":"The artifact id value for this approvalartifactout.","examples":["msgart_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"artifact_version":{"type":"string","const":"2026-07-13","title":"Artifact Version","description":"The artifact version value for this approvalartifactout."},"artifact_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Artifact Hash","description":"The artifact hash value for this approvalartifactout.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]}},"additionalProperties":false,"type":"object","required":["artifact_kind","artifact_id","artifact_version","artifact_hash"],"title":"ApprovalArtifactOut","description":"Structured approvalartifactout data exposed by the public API.","examples":[{"artifact_kind":"message","artifact_id":"msgart_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","artifact_version":"2026-07-13","artifact_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}]},"ArtifactStyle":{"properties":{"corner_style":{"type":"string","enum":["square","subtle","rounded","pill","mixed"],"title":"Corner Style","default":"subtle","description":"The corner style value for this artifactstyle."},"surface_treatment":{"type":"string","enum":["flat","gradient","image_led","editorial","textured","mixed"],"title":"Surface Treatment","default":"flat","description":"The surface treatment value for this artifactstyle."},"border_treatment":{"type":"string","enum":["none","hairline","strong","decorative","mixed"],"title":"Border Treatment","default":"hairline","description":"The border treatment value for this artifactstyle."},"heading_case":{"type":"string","enum":["sentence","title","uppercase","mixed"],"title":"Heading Case","default":"sentence","description":"The heading case value for this artifactstyle."},"density":{"type":"string","enum":["compact","comfortable","spacious"],"title":"Density","default":"comfortable","description":"The density value for this artifactstyle."},"button_style":{"type":"string","enum":["square","subtle","rounded","pill","underline"],"title":"Button Style","default":"subtle","description":"The button style value for this artifactstyle."},"image_treatment":{"type":"string","enum":["full_bleed","contained","masked","overlay","mixed"],"title":"Image Treatment","default":"overlay","description":"The image treatment value for this artifactstyle."},"rationale":{"anyOf":[{"type":"string","maxLength":800},{"type":"null"}],"title":"Rationale","description":"The rationale value for this artifactstyle.","examples":["Example rationale"]}},"additionalProperties":false,"type":"object","title":"ArtifactStyle","description":"Structured artifactstyle data exposed by the public API.","examples":[{}]},"AudienceCreateIn":{"properties":{"key":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z][a-z0-9._-]*$","title":"Key","description":"The key value for this audiencecreatein.","examples":["example_key"]},"name":{"type":"string","maxLength":240,"minLength":1,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"Name","description":"The name value for this audiencecreatein.","examples":["Example value"]},"prospecting_job_id":{"type":"string","pattern":"^job_[a-f0-9]{24}$","title":"Prospecting Job Id","description":"The prospecting job id value for this audiencecreatein.","examples":["job_aaaaaaaaaaaaaaaaaaaaaaaa"]},"prospect_ids":{"anyOf":[{"items":{"type":"string","maxLength":120,"minLength":1,"pattern":"^[^\\x00-\\x1f\\x7f]+$"},"type":"array","maxItems":100,"minItems":1},{"type":"null"}],"title":"Prospect Ids","description":"The prospect ids value for this audiencecreatein.","examples":[["Example value"]]},"external_ref":{"anyOf":[{"type":"string","maxLength":240,"minLength":1,"pattern":"^[^\\x00-\\x1f\\x7f]+$"},{"type":"null"}],"title":"External Ref","description":"The external ref value for this audiencecreatein.","examples":["Example value"]}},"additionalProperties":false,"type":"object","required":["key","name","prospecting_job_id"],"title":"AudienceCreateIn","description":"Materialize an immutable review snapshot from one typed prospecting result.","examples":[{"key":"example_key","name":"Example value","prospecting_job_id":"job_aaaaaaaaaaaaaaaaaaaaaaaa"}]},"AudienceInput":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":160,"minLength":1},{"type":"null"}],"title":"Name","description":"Optional saved-campaign name. Defaults to a shortened objective when omitted.","examples":["North America RevOps leaders"]},"objective":{"type":"string","maxLength":4000,"minLength":1,"title":"Objective","description":"Required description of the companies and buyers the audience should contain.","examples":["Find VP and director-level revenue operations leaders at B2B SaaS companies."]},"website_url":{"anyOf":[{"type":"string","maxLength":253,"minLength":3,"pattern":"^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"},{"type":"null"}],"format":"hostname","title":"Website Url","description":"Optional seller website domain used as product context.","examples":["northstar.example"]},"product_name":{"anyOf":[{"type":"string","maxLength":160,"minLength":1},{"type":"null"}],"title":"Product Name","description":"Optional product name used to build the ideal customer profile.","examples":["Northstar Analytics"]},"product_description":{"anyOf":[{"type":"string","maxLength":12000,"minLength":1},{"type":"null"}],"title":"Product Description","description":"Optional product description used to refine the ideal customer profile.","examples":["Revenue-intelligence software for enterprise sales teams."]},"icp_description":{"anyOf":[{"type":"string","maxLength":8000,"minLength":1},{"type":"null"}],"title":"Icp Description","description":"Optional pre-existing ideal-customer-profile guidance.","examples":["Enterprise B2B SaaS companies with complex revenue operations."]},"additional_context":{"anyOf":[{"type":"string","maxLength":12000,"minLength":1},{"type":"null"}],"title":"Additional Context","description":"Optional additional targeting context, exclusions, or business constraints.","examples":["Prioritize companies hiring for RevOps in North America."]},"b2b":{"type":"boolean","title":"B2B","description":"Whether the target audience is business-to-business.","default":true,"examples":[true]},"skip_intent":{"type":"boolean","title":"Skip Intent","description":"Skip intent-topic discovery when an existing ICP is sufficient.","default":false,"examples":[false]},"target_size":{"type":"integer","maximum":2000.0,"minimum":1.0,"title":"Target Size","description":"Requested maximum number of audience candidates before server-side plan limits apply.","default":100,"examples":[100]},"max_contacts_per_company":{"type":"integer","maximum":10.0,"minimum":1.0,"title":"Max Contacts Per Company","description":"Maximum contacts returned for each company candidate.","default":3,"examples":[3]},"excluded_domains":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":200,"minItems":1},{"type":"null"}],"title":"Excluded Domains","description":"Company domains excluded from this run. URLs are normalized to domains.","examples":[["existing-customer.example"]]},"playbooks_enabled":{"type":"boolean","title":"Playbooks Enabled","description":"Whether the audience pipeline should generate candidate playbooks when the capability is entitled.","default":false,"examples":[false]},"model":{"type":"string","enum":["default"],"const":"default","title":"Model","description":"Audience-generation model selection. `default` is the currently supported model.","default":"default","examples":["default"]}},"additionalProperties":false,"type":"object","required":["objective"],"title":"AudienceInput","description":"Stable public input shape for Audiences.\n\nOnly `objective` is required; everything else refines the ICP or bounds the\npipeline. Sizing fields are additionally clamped server-side by settings.","examples":[{"excluded_domains":["existing-customer.example"],"max_contacts_per_company":3,"model":"default","name":"North America RevOps leaders","objective":"Find VP and director-level revenue operations leaders at B2B SaaS companies.","playbooks_enabled":false,"product_description":"Revenue-intelligence software for enterprise sales teams.","product_name":"Northstar Analytics","target_size":100,"website_url":"northstar.example"}]},"AudienceMemberOut":{"properties":{"id":{"type":"string","title":"Id","description":"The id value for this audiencememberout.","examples":["Example id"]},"audience_id":{"type":"string","title":"Audience Id","description":"The audience id value for this audiencememberout.","examples":["Example audience id"]},"project_id":{"type":"string","title":"Project Id","description":"The project id value for this audiencememberout.","examples":["Example project id"]},"environment":{"type":"string","enum":["live","test"],"title":"Environment","description":"The environment value for this audiencememberout.","examples":["live"]},"prospecting_job_id":{"type":"string","title":"Prospecting Job Id","description":"The prospecting job id value for this audiencememberout.","examples":["Example prospecting job id"]},"prospecting_result_hash":{"type":"string","title":"Prospecting Result Hash","description":"The prospecting result hash value for this audiencememberout.","examples":["Example prospecting result hash"]},"prospect_id":{"type":"string","title":"Prospect Id","description":"The prospect id value for this audiencememberout.","examples":["Example prospect id"]},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id","description":"The external id value for this audiencememberout.","examples":["Example external id"]},"is_synthetic":{"type":"boolean","const":false,"title":"Is Synthetic","description":"The is synthetic value for this audiencememberout."},"profile":{"$ref":"#/components/schemas/ProspectProfile","description":"The profile value for this audiencememberout.","examples":[{"company":{}}]},"qualification":{"$ref":"#/components/schemas/Qualification","description":"The qualification value for this audiencememberout.","examples":[{"status":"qualified","score":0.0,"confidence":0.0,"reason":"Example reason","selection_strategy":"cold_start"}]},"enrichment":{"$ref":"#/components/schemas/ProspectEnrichment","description":"The enrichment value for this audiencememberout.","examples":[{"status":"not_requested"}]},"outreach":{"$ref":"#/components/schemas/ProspectOutreach","description":"The outreach value for this audiencememberout.","examples":[{"state":"not_ready"}]},"evidence":{"items":{"$ref":"#/components/schemas/EvidenceRef"},"type":"array","title":"Evidence","description":"The evidence value for this audiencememberout.","examples":[[{"id":"Example id","source":"web","label":"Example label","confidence":0.0}]]},"evidence_count":{"type":"integer","title":"Evidence Count","description":"The evidence count value for this audiencememberout.","examples":[0]},"review_status":{"type":"string","enum":["pending","included","excluded"],"title":"Review Status","description":"The review status value for this audiencememberout.","examples":["pending"]},"review_reason_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Review Reason Code","description":"The review reason code value for this audiencememberout.","examples":["Example review reason code"]},"reviewed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reviewed At","description":"The reviewed at value for this audiencememberout.","examples":["2026-07-16T00:00:00Z"]},"outbound_authorized":{"type":"boolean","const":false,"title":"Outbound Authorized","description":"The outbound authorized value for this audiencememberout."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"The created at value for this audiencememberout.","examples":["2026-07-16T00:00:00Z"]}},"type":"object","required":["id","audience_id","project_id","environment","prospecting_job_id","prospecting_result_hash","prospect_id","external_id","is_synthetic","profile","qualification","enrichment","outreach","evidence","evidence_count","review_status","review_reason_code","reviewed_at","outbound_authorized","created_at"],"title":"AudienceMemberOut","description":"Structured audiencememberout data exposed by the public API.","examples":[{"id":"Example id","audience_id":"Example audience id","project_id":"Example project id","environment":"live","prospecting_job_id":"Example prospecting job id","prospecting_result_hash":"Example prospecting result hash","prospect_id":"Example prospect id","external_id":"Example external id","is_synthetic":false,"profile":{"company":{}},"qualification":{"status":"qualified","score":0.0,"confidence":0.0,"reason":"Example reason","selection_strategy":"cold_start"},"enrichment":{"status":"not_requested"},"outreach":{"state":"not_ready"},"evidence":[{"id":"Example id","source":"web","label":"Example label","confidence":0.0}],"evidence_count":0,"review_status":"pending","review_reason_code":"Example review reason code","reviewed_at":"2026-07-16T00:00:00Z","outbound_authorized":false,"created_at":"2026-07-16T00:00:00Z"}]},"AudienceMembersResponse":{"properties":{"members":{"items":{"$ref":"#/components/schemas/AudienceMemberOut"},"type":"array","title":"Members","description":"The members value for this audiencemembersresponse.","examples":[[{"id":"Example id","audience_id":"Example audience id","project_id":"Example project id","environment":"live","prospecting_job_id":"Example prospecting job id","prospecting_result_hash":"Example prospecting result hash","prospect_id":"Example prospect id","external_id":"Example external id","is_synthetic":false,"profile":{"company":{}},"qualification":{"status":"qualified","score":0.0,"confidence":0.0,"reason":"Example reason","selection_strategy":"cold_start"},"enrichment":{"status":"not_requested"},"outreach":{"state":"not_ready"},"evidence":[{"id":"Example id","source":"web","label":"Example label","confidence":0.0}],"evidence_count":0,"review_status":"pending","review_reason_code":"Example review reason code","reviewed_at":"2026-07-16T00:00:00Z","outbound_authorized":false,"created_at":"2026-07-16T00:00:00Z"}]]},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"The next cursor value for this audiencemembersresponse.","examples":["Example next cursor"]},"total":{"type":"integer","title":"Total","description":"The total value for this audiencemembersresponse.","examples":[0]}},"type":"object","required":["members","next_cursor","total"],"title":"AudienceMembersResponse","description":"Structured audiencemembersresponse data exposed by the public API.","examples":[{"members":[{"id":"Example id","audience_id":"Example audience id","project_id":"Example project id","environment":"live","prospecting_job_id":"Example prospecting job id","prospecting_result_hash":"Example prospecting result hash","prospect_id":"Example prospect id","external_id":"Example external id","is_synthetic":false,"profile":{"company":{}},"qualification":{"status":"qualified","score":0.0,"confidence":0.0,"reason":"Example reason","selection_strategy":"cold_start"},"enrichment":{"status":"not_requested"},"outreach":{"state":"not_ready"},"evidence":[{"id":"Example id","source":"web","label":"Example label","confidence":0.0}],"evidence_count":0,"review_status":"pending","review_reason_code":"Example review reason code","reviewed_at":"2026-07-16T00:00:00Z","outbound_authorized":false,"created_at":"2026-07-16T00:00:00Z"}],"next_cursor":"Example next cursor","total":0}]},"AudienceOut":{"properties":{"id":{"type":"string","title":"Id","description":"The id value for this audienceout.","examples":["Example id"]},"status":{"type":"string","const":"active","title":"Status","description":"The status value for this audienceout."},"idempotent_replay":{"type":"boolean","title":"Idempotent Replay","description":"The idempotent replay value for this audienceout.","examples":[true]},"key":{"type":"string","title":"Key","description":"The key value for this audienceout.","examples":["Example key"]},"name":{"type":"string","title":"Name","description":"The name value for this audienceout.","examples":["Example name"]},"project_id":{"type":"string","title":"Project Id","description":"The project id value for this audienceout.","examples":["Example project id"]},"environment":{"type":"string","enum":["live","test"],"title":"Environment","description":"The environment value for this audienceout.","examples":["live"]},"prospecting_job_id":{"type":"string","title":"Prospecting Job Id","description":"The prospecting job id value for this audienceout.","examples":["Example prospecting job id"]},"prospecting_result_hash":{"type":"string","title":"Prospecting Result Hash","description":"The prospecting result hash value for this audienceout.","examples":["Example prospecting result hash"]},"external_ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Ref","description":"The external ref value for this audienceout.","examples":["Example external ref"]},"member_count":{"type":"integer","title":"Member Count","description":"The member count value for this audienceout.","examples":[0]},"review_counts":{"$ref":"#/components/schemas/AudienceReviewCounts","description":"The review counts value for this audienceout.","examples":[{"pending":0,"included":0,"excluded":0}]},"outbound_authorized":{"type":"boolean","const":false,"title":"Outbound Authorized","description":"The outbound authorized value for this audienceout."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"The created at value for this audienceout.","examples":["2026-07-16T00:00:00Z"]}},"type":"object","required":["id","status","idempotent_replay","key","name","project_id","environment","prospecting_job_id","prospecting_result_hash","external_ref","member_count","review_counts","outbound_authorized","created_at"],"title":"AudienceOut","description":"Structured audienceout data exposed by the public API.","examples":[{"id":"Example id","status":"active","idempotent_replay":true,"key":"Example key","name":"Example name","project_id":"Example project id","environment":"live","prospecting_job_id":"Example prospecting job id","prospecting_result_hash":"Example prospecting result hash","external_ref":"Example external ref","member_count":0,"review_counts":{"pending":0,"included":0,"excluded":0},"outbound_authorized":false,"created_at":"2026-07-16T00:00:00Z"}]},"AudienceReviewCounts":{"properties":{"pending":{"type":"integer","title":"Pending","description":"The pending value for this audiencereviewcounts.","examples":[0]},"included":{"type":"integer","title":"Included","description":"The included value for this audiencereviewcounts.","examples":[0]},"excluded":{"type":"integer","title":"Excluded","description":"The excluded value for this audiencereviewcounts.","examples":[0]}},"type":"object","required":["pending","included","excluded"],"title":"AudienceReviewCounts","description":"Structured audiencereviewcounts data exposed by the public API.","examples":[{"pending":0,"included":0,"excluded":0}]},"AudienceReviewCreateIn":{"properties":{"review_key":{"type":"string","maxLength":240,"minLength":1,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"Review Key","description":"The review key value for this audiencereviewcreatein.","examples":["Example value"]},"member_ids":{"items":{"type":"string","pattern":"^audmem_[a-f0-9]{24}$"},"type":"array","maxItems":100,"minItems":1,"title":"Member Ids","description":"The member ids value for this audiencereviewcreatein.","examples":[["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"]]},"decision":{"type":"string","enum":["included","excluded"],"title":"Decision","description":"The decision value for this audiencereviewcreatein.","examples":["included"]},"reason_code":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z][a-z0-9._-]*$","title":"Reason Code","description":"The reason code value for this audiencereviewcreatein.","examples":["example_key"]}},"additionalProperties":false,"type":"object","required":["review_key","member_ids","decision","reason_code"],"title":"AudienceReviewCreateIn","description":"Structured audiencereviewcreatein data exposed by the public API.","examples":[{"review_key":"Example value","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"decision":"included","reason_code":"example_key"}]},"AudienceReviewOut":{"properties":{"id":{"type":"string","title":"Id","description":"The id value for this audiencereviewout.","examples":["Example id"]},"status":{"type":"string","const":"recorded","title":"Status","description":"The status value for this audiencereviewout."},"idempotent_replay":{"type":"boolean","title":"Idempotent Replay","description":"The idempotent replay value for this audiencereviewout.","examples":[true]},"audience_id":{"type":"string","title":"Audience Id","description":"The audience id value for this audiencereviewout.","examples":["Example audience id"]},"review_key":{"type":"string","title":"Review Key","description":"The review key value for this audiencereviewout.","examples":["Example review key"]},"decision":{"type":"string","enum":["included","excluded"],"title":"Decision","description":"The decision value for this audiencereviewout.","examples":["included"]},"reason_code":{"type":"string","title":"Reason Code","description":"The reason code value for this audiencereviewout.","examples":["Example reason code"]},"member_ids":{"items":{"type":"string"},"type":"array","title":"Member Ids","description":"The member ids value for this audiencereviewout.","examples":[["Example member ids"]]},"changed_count":{"type":"integer","title":"Changed Count","description":"The changed count value for this audiencereviewout.","examples":[0]},"recorded_at":{"type":"string","format":"date-time","title":"Recorded At","description":"The recorded at value for this audiencereviewout.","examples":["2026-07-16T00:00:00Z"]}},"type":"object","required":["id","status","idempotent_replay","audience_id","review_key","decision","reason_code","member_ids","changed_count","recorded_at"],"title":"AudienceReviewOut","description":"Structured audiencereviewout data exposed by the public API.","examples":[{"id":"Example id","status":"recorded","idempotent_replay":true,"audience_id":"Example audience id","review_key":"Example review key","decision":"included","reason_code":"Example reason code","member_ids":["Example member ids"],"changed_count":0,"recorded_at":"2026-07-16T00:00:00Z"}]},"AudienceSegment":{"properties":{"name":{"type":"string","maxLength":160,"title":"Name","description":"The name value for this audiencesegment.","examples":["Example name"]},"description":{"type":"string","maxLength":1000,"title":"Description","description":"The description value for this audiencesegment.","examples":["Example description"]},"needs":{"items":{"type":"string"},"type":"array","maxItems":12,"title":"Needs","description":"The needs value for this audiencesegment.","examples":[["Example needs"]]},"pain_points":{"items":{"type":"string"},"type":"array","maxItems":12,"title":"Pain Points","description":"The pain points value for this audiencesegment.","examples":[["Example pain points"]]},"desired_outcomes":{"items":{"type":"string"},"type":"array","maxItems":12,"title":"Desired Outcomes","description":"The desired outcomes value for this audiencesegment.","examples":[["Example desired outcomes"]]}},"additionalProperties":false,"type":"object","required":["name","description"],"title":"AudienceSegment","description":"Structured audiencesegment data exposed by the public API.","examples":[{"name":"Example name","description":"Example description"}]},"AudiencesResponse":{"properties":{"audiences":{"items":{"$ref":"#/components/schemas/AudienceOut"},"type":"array","title":"Audiences","description":"The audiences value for this audiencesresponse.","examples":[[{"id":"Example id","status":"active","idempotent_replay":true,"key":"Example key","name":"Example name","project_id":"Example project id","environment":"live","prospecting_job_id":"Example prospecting job id","prospecting_result_hash":"Example prospecting result hash","external_ref":"Example external ref","member_count":0,"review_counts":{"pending":0,"included":0,"excluded":0},"outbound_authorized":false,"created_at":"2026-07-16T00:00:00Z"}]]},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"The next cursor value for this audiencesresponse.","examples":["Example next cursor"]},"total":{"type":"integer","title":"Total","description":"The total value for this audiencesresponse.","examples":[0]}},"type":"object","required":["audiences","next_cursor","total"],"title":"AudiencesResponse","description":"Structured audiencesresponse data exposed by the public API.","examples":[{"audiences":[{"id":"Example id","status":"active","idempotent_replay":true,"key":"Example key","name":"Example name","project_id":"Example project id","environment":"live","prospecting_job_id":"Example prospecting job id","prospecting_result_hash":"Example prospecting result hash","external_ref":"Example external ref","member_count":0,"review_counts":{"pending":0,"included":0,"excluded":0},"outbound_authorized":false,"created_at":"2026-07-16T00:00:00Z"}],"next_cursor":"Example next cursor","total":0}]},"BrandApplications":{"properties":{"documents":{"items":{"type":"string"},"type":"array","maxItems":16,"title":"Documents","description":"The documents value for this brandapplications.","examples":[["Example documents"]]},"presentations":{"items":{"type":"string"},"type":"array","maxItems":16,"title":"Presentations","description":"The presentations value for this brandapplications.","examples":[["Example presentations"]]},"email":{"items":{"type":"string"},"type":"array","maxItems":16,"title":"Email","description":"The email value for this brandapplications.","examples":[["Example email"]]},"social":{"items":{"type":"string"},"type":"array","maxItems":16,"title":"Social","description":"The social value for this brandapplications.","examples":[["Example social"]]},"website_ui":{"items":{"type":"string"},"type":"array","maxItems":16,"title":"Website Ui","description":"The website ui value for this brandapplications.","examples":[["Example website ui"]]}},"additionalProperties":false,"type":"object","title":"BrandApplications","description":"Structured brandapplications data exposed by the public API.","examples":[{}]},"BrandAudience":{"properties":{"primary":{"items":{"$ref":"#/components/schemas/AudienceSegment"},"type":"array","maxItems":8,"title":"Primary","description":"The primary value for this brandaudience.","examples":[[{"name":"Example name","description":"Example description"}]]},"secondary":{"items":{"$ref":"#/components/schemas/AudienceSegment"},"type":"array","maxItems":8,"title":"Secondary","description":"The secondary value for this brandaudience.","examples":[[{"name":"Example name","description":"Example description"}]]},"audience_principles":{"items":{"type":"string"},"type":"array","maxItems":12,"title":"Audience Principles","description":"The audience principles value for this brandaudience.","examples":[["Example audience principles"]]},"evidence":{"$ref":"#/components/schemas/SectionEvidence","description":"The evidence value for this brandaudience.","examples":[{}]}},"additionalProperties":false,"type":"object","title":"BrandAudience","description":"Structured brandaudience data exposed by the public API.","examples":[{}]},"BrandBoilerplates":{"properties":{"short":{"anyOf":[{"type":"string","maxLength":400},{"type":"null"}],"title":"Short","description":"The short value for this brandboilerplates.","examples":["Example short"]},"medium":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Medium","description":"The medium value for this brandboilerplates.","examples":["Example medium"]},"long":{"anyOf":[{"type":"string","maxLength":2500},{"type":"null"}],"title":"Long","description":"The long value for this brandboilerplates.","examples":["Example long"]}},"additionalProperties":false,"type":"object","title":"BrandBoilerplates","description":"Structured brandboilerplates data exposed by the public API.","examples":[{}]},"BrandColor":{"properties":{"name":{"type":"string","maxLength":120,"title":"Name","description":"The name value for this brandcolor.","examples":["Example name"]},"role":{"type":"string","maxLength":120,"title":"Role","description":"The role value for this brandcolor.","examples":["Example role"]},"hex":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$","title":"Hex","description":"The hex value for this brandcolor.","examples":["#0057B8"]},"rgb":{"type":"string","maxLength":80,"title":"Rgb","description":"The rgb value for this brandcolor.","examples":["Example rgb"]},"cmyk":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Cmyk","description":"The cmyk value for this brandcolor.","examples":["Example cmyk"]},"usage":{"type":"string","maxLength":600,"title":"Usage","description":"The usage value for this brandcolor.","examples":["Example usage"]},"contrast_guidance":{"anyOf":[{"type":"string","maxLength":600},{"type":"null"}],"title":"Contrast Guidance","description":"The contrast guidance value for this brandcolor.","examples":["Example contrast guidance"]},"source_ids":{"items":{"type":"string"},"type":"array","maxItems":10,"title":"Source Ids","description":"The source ids value for this brandcolor.","examples":[["Example source ids"]]}},"additionalProperties":false,"type":"object","required":["name","role","hex","rgb","usage"],"title":"BrandColor","description":"Structured brandcolor data exposed by the public API.","examples":[{"name":"Example name","role":"Example role","hex":"#0057B8","rgb":"Example rgb","usage":"Example usage"}]},"BrandFoundations":{"properties":{"purpose":{"anyOf":[{"type":"string","maxLength":1200},{"type":"null"}],"title":"Purpose","description":"The purpose value for this brandfoundations.","examples":["Example purpose"]},"mission":{"anyOf":[{"type":"string","maxLength":1200},{"type":"null"}],"title":"Mission","description":"The mission value for this brandfoundations.","examples":["Example mission"]},"vision":{"anyOf":[{"type":"string","maxLength":1200},{"type":"null"}],"title":"Vision","description":"The vision value for this brandfoundations.","examples":["Example vision"]},"brand_promise":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Brand Promise","description":"The brand promise value for this brandfoundations.","examples":["Example brand promise"]},"story":{"anyOf":[{"type":"string","maxLength":3000},{"type":"null"}],"title":"Story","description":"The story value for this brandfoundations.","examples":["Example story"]},"values":{"items":{"$ref":"#/components/schemas/BrandValue"},"type":"array","maxItems":12,"title":"Values","description":"The values value for this brandfoundations.","examples":[[{"name":"Example name","description":"Example description"}]]},"personality_traits":{"items":{"$ref":"#/components/schemas/PersonalityTrait"},"type":"array","maxItems":10,"title":"Personality Traits","description":"The personality traits value for this brandfoundations.","examples":[[{"name":"Example name","description":"Example description","we_are":"Example we are","we_are_not":"Example we are not"}]]},"archetypes":{"items":{"type":"string"},"type":"array","maxItems":5,"title":"Archetypes","description":"The archetypes value for this brandfoundations.","examples":[["Example archetypes"]]},"evidence":{"$ref":"#/components/schemas/SectionEvidence","description":"The evidence value for this brandfoundations.","examples":[{}]}},"additionalProperties":false,"type":"object","title":"BrandFoundations","description":"Structured brandfoundations data exposed by the public API.","examples":[{}]},"BrandGovernance":{"properties":{"logo_rules":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Logo Rules","description":"The logo rules value for this brandgovernance.","examples":[["Example logo rules"]]},"color_rules":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Color Rules","description":"The color rules value for this brandgovernance.","examples":[["Example color rules"]]},"typography_rules":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Typography Rules","description":"The typography rules value for this brandgovernance.","examples":[["Example typography rules"]]},"accessibility_rules":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Accessibility Rules","description":"The accessibility rules value for this brandgovernance.","examples":[["Example accessibility rules"]]},"required_disclaimers":{"items":{"type":"string"},"type":"array","maxItems":12,"title":"Required Disclaimers","description":"The required disclaimers value for this brandgovernance.","examples":[["Example required disclaimers"]]},"prohibited_uses":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Prohibited Uses","description":"The prohibited uses value for this brandgovernance.","examples":[["Example prohibited uses"]]},"approval_notes":{"items":{"type":"string"},"type":"array","maxItems":12,"title":"Approval Notes","description":"The approval notes value for this brandgovernance.","examples":[["Example approval notes"]]}},"additionalProperties":false,"type":"object","title":"BrandGovernance","description":"Structured brandgovernance data exposed by the public API.","examples":[{}]},"BrandGuidelineDocument":{"properties":{"identity":{"$ref":"#/components/schemas/BrandIdentity","description":"The identity value for this brandguidelinedocument.","examples":[{"name":"Example name","short_description":"Example short description","long_description":"Example long description"}]},"foundations":{"$ref":"#/components/schemas/BrandFoundations","description":"The foundations value for this brandguidelinedocument.","examples":[{}]},"audience":{"$ref":"#/components/schemas/BrandAudience","description":"The audience value for this brandguidelinedocument.","examples":[{}]},"positioning":{"$ref":"#/components/schemas/BrandPositioning","description":"The positioning value for this brandguidelinedocument.","examples":[{}]},"voice":{"$ref":"#/components/schemas/BrandVoice","description":"The voice value for this brandguidelinedocument.","examples":[{"summary":"Example summary"}]},"messaging":{"$ref":"#/components/schemas/BrandMessaging","description":"The messaging value for this brandguidelinedocument.","examples":[{}]},"visual":{"$ref":"#/components/schemas/BrandVisualSystem","description":"The visual value for this brandguidelinedocument.","examples":[{}]},"applications":{"$ref":"#/components/schemas/BrandApplications","description":"The applications value for this brandguidelinedocument.","examples":[{}]},"governance":{"$ref":"#/components/schemas/BrandGovernance","description":"The governance value for this brandguidelinedocument.","examples":[{}]},"research":{"$ref":"#/components/schemas/BrandResearchProvenance","description":"The research value for this brandguidelinedocument.","examples":[{}]},"schema_version":{"type":"string","title":"Schema Version","description":"The schema version value for this brandguidelinedocument.","examples":["Example schema version"]},"brand_profile_id":{"type":"string","title":"Brand Profile Id","description":"The brand profile id value for this brandguidelinedocument.","examples":["Example brand profile id"]},"revision":{"type":"integer","minimum":1.0,"title":"Revision","description":"The revision value for this brandguidelinedocument.","examples":[1]},"generated_at":{"type":"string","title":"Generated At","description":"The generated at value for this brandguidelinedocument.","examples":["Example generated at"]},"generation":{"$ref":"#/components/schemas/GuidelineGeneration","description":"The generation value for this brandguidelinedocument.","examples":[{"provider":"openai","model":"Example model"}]},"guideline_hash":{"type":"string","title":"Guideline Hash","description":"The guideline hash value for this brandguidelinedocument.","examples":["Example guideline hash"]},"markdown":{"type":"string","title":"Markdown","description":"The markdown value for this brandguidelinedocument.","examples":["Example markdown"]}},"additionalProperties":false,"type":"object","required":["identity","foundations","audience","positioning","voice","messaging","visual","applications","governance","research","schema_version","brand_profile_id","revision","generated_at","generation","guideline_hash","markdown"],"title":"BrandGuidelineDocument","description":"Structured brandguidelinedocument data exposed by the public API.","examples":[{"identity":{"name":"Example name","short_description":"Example short description","long_description":"Example long description"},"foundations":{},"audience":{},"positioning":{},"voice":{"summary":"Example summary"},"messaging":{},"visual":{},"applications":{},"governance":{},"research":{},"schema_version":"Example schema version","brand_profile_id":"Example brand profile id","revision":1,"generated_at":"Example generated at","generation":{"provider":"openai","model":"Example model"},"guideline_hash":"Example guideline hash","markdown":"Example markdown"}]},"BrandIdentity":{"properties":{"name":{"type":"string","maxLength":160,"title":"Name","description":"The name value for this brandidentity.","examples":["Example name"]},"legal_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Legal Name","description":"The legal name value for this brandidentity.","examples":["Example legal name"]},"pronunciation":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Pronunciation","description":"The pronunciation value for this brandidentity.","examples":["Example pronunciation"]},"website":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Website","description":"The website value for this brandidentity.","examples":["Example website"]},"tagline":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Tagline","description":"The tagline value for this brandidentity.","examples":["Example tagline"]},"descriptor":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Descriptor","description":"The descriptor value for this brandidentity.","examples":["Example descriptor"]},"short_description":{"type":"string","maxLength":600,"title":"Short Description","description":"The short description value for this brandidentity.","examples":["Example short description"]},"long_description":{"type":"string","maxLength":3000,"title":"Long Description","description":"The long description value for this brandidentity.","examples":["Example long description"]},"founded_year":{"anyOf":[{"type":"integer","maximum":2200.0,"minimum":1000.0},{"type":"null"}],"title":"Founded Year","description":"The founded year value for this brandidentity.","examples":[1000]},"headquarters":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Headquarters","description":"The headquarters value for this brandidentity.","examples":["Example headquarters"]},"industries":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Industries","description":"The industries value for this brandidentity.","examples":[["Example industries"]]},"offerings":{"items":{"type":"string"},"type":"array","maxItems":30,"title":"Offerings","description":"The offerings value for this brandidentity.","examples":[["Example offerings"]]},"evidence":{"$ref":"#/components/schemas/SectionEvidence","description":"The evidence value for this brandidentity.","examples":[{}]}},"additionalProperties":false,"type":"object","required":["name","short_description","long_description"],"title":"BrandIdentity","description":"Structured brandidentity data exposed by the public API.","examples":[{"name":"Example name","short_description":"Example short description","long_description":"Example long description"}]},"BrandMessaging":{"properties":{"elevator_pitch":{"anyOf":[{"type":"string","maxLength":1200},{"type":"null"}],"title":"Elevator Pitch","description":"The elevator pitch value for this brandmessaging.","examples":["Example elevator pitch"]},"pillars":{"items":{"$ref":"#/components/schemas/MessagingPillar"},"type":"array","maxItems":10,"title":"Pillars","description":"The pillars value for this brandmessaging.","examples":[[{"name":"Example name","message":"Example message"}]]},"boilerplates":{"$ref":"#/components/schemas/BrandBoilerplates","description":"The boilerplates value for this brandmessaging.","examples":[{}]},"proof_points":{"items":{"type":"string"},"type":"array","maxItems":24,"title":"Proof Points","description":"The proof points value for this brandmessaging.","examples":[["Example proof points"]]},"objection_responses":{"items":{"type":"string"},"type":"array","maxItems":12,"title":"Objection Responses","description":"The objection responses value for this brandmessaging.","examples":[["Example objection responses"]]},"evidence":{"$ref":"#/components/schemas/SectionEvidence","description":"The evidence value for this brandmessaging.","examples":[{}]}},"additionalProperties":false,"type":"object","title":"BrandMessaging","description":"Structured brandmessaging data exposed by the public API.","examples":[{}]},"BrandPositioning":{"properties":{"category":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Category","description":"The category value for this brandpositioning.","examples":["Example category"]},"positioning_statement":{"anyOf":[{"type":"string","maxLength":1500},{"type":"null"}],"title":"Positioning Statement","description":"The positioning statement value for this brandpositioning.","examples":["Example positioning statement"]},"value_proposition":{"anyOf":[{"type":"string","maxLength":1500},{"type":"null"}],"title":"Value Proposition","description":"The value proposition value for this brandpositioning.","examples":["Example value proposition"]},"competitive_context":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Competitive Context","description":"The competitive context value for this brandpositioning.","examples":["Example competitive context"]},"differentiators":{"items":{"$ref":"#/components/schemas/Differentiator"},"type":"array","maxItems":12,"title":"Differentiators","description":"The differentiators value for this brandpositioning.","examples":[[{"name":"Example name","description":"Example description"}]]},"evidence":{"$ref":"#/components/schemas/SectionEvidence","description":"The evidence value for this brandpositioning.","examples":[{}]}},"additionalProperties":false,"type":"object","title":"BrandPositioning","description":"Structured brandpositioning data exposed by the public API.","examples":[{}]},"BrandResearchProvenance":{"properties":{"sources":{"items":{"$ref":"#/components/schemas/ResearchSource"},"type":"array","maxItems":100,"title":"Sources","description":"The sources value for this brandresearchprovenance.","examples":[[{"id":"Example id","url":"https://example.com","title":"Example title","source_type":"official"}]]},"section_confidence":{"items":{"$ref":"#/components/schemas/SectionConfidence"},"type":"array","maxItems":20,"title":"Section Confidence","description":"The section confidence value for this brandresearchprovenance.","examples":[[{"section":"Example section","confidence":"high","rationale":"Example rationale"}]]},"limitations":{"items":{"type":"string"},"type":"array","maxItems":30,"title":"Limitations","description":"The limitations value for this brandresearchprovenance.","examples":[["Example limitations"]]},"assumptions":{"items":{"type":"string"},"type":"array","maxItems":30,"title":"Assumptions","description":"The assumptions value for this brandresearchprovenance.","examples":[["Example assumptions"]]}},"additionalProperties":false,"type":"object","title":"BrandResearchProvenance","description":"Structured brandresearchprovenance data exposed by the public API.","examples":[{}]},"BrandValue":{"properties":{"name":{"type":"string","maxLength":120,"title":"Name","description":"The name value for this brandvalue.","examples":["Example name"]},"description":{"type":"string","maxLength":800,"title":"Description","description":"The description value for this brandvalue.","examples":["Example description"]}},"additionalProperties":false,"type":"object","required":["name","description"],"title":"BrandValue","description":"Structured brandvalue data exposed by the public API.","examples":[{"name":"Example name","description":"Example description"}]},"BrandVisualSystem":{"properties":{"logos":{"items":{"$ref":"#/components/schemas/LogoAsset"},"type":"array","maxItems":16,"title":"Logos","description":"The logos value for this brandvisualsystem.","examples":[[{"name":"Example name","url":"https://example.com","variant":"Example variant"}]]},"colors":{"items":{"$ref":"#/components/schemas/BrandColor"},"type":"array","maxItems":20,"title":"Colors","description":"The colors value for this brandvisualsystem.","examples":[[{"name":"Example name","role":"Example role","hex":"#0057B8","rgb":"Example rgb","usage":"Example usage"}]]},"typography":{"items":{"$ref":"#/components/schemas/Typeface"},"type":"array","maxItems":10,"title":"Typography","description":"The typography value for this brandvisualsystem.","examples":[[{"role":"Example role","family":"Example family","usage":"Example usage"}]]},"images":{"items":{"$ref":"#/components/schemas/FocusImageAsset"},"type":"array","maxItems":12,"title":"Images","description":"The images value for this brandvisualsystem.","examples":[[{"name":"Example name","url":"https://example.com","alt_text":"Example alt text"}]]},"artifact_style":{"$ref":"#/components/schemas/ArtifactStyle","description":"The artifact style value for this brandvisualsystem.","examples":[{}]},"direction":{"$ref":"#/components/schemas/VisualDirection","description":"The direction value for this brandvisualsystem.","examples":[{}]},"layout_principles":{"items":{"type":"string"},"type":"array","maxItems":16,"title":"Layout Principles","description":"The layout principles value for this brandvisualsystem.","examples":[["Example layout principles"]]},"accessibility_notes":{"items":{"type":"string"},"type":"array","maxItems":16,"title":"Accessibility Notes","description":"The accessibility notes value for this brandvisualsystem.","examples":[["Example accessibility notes"]]},"evidence":{"$ref":"#/components/schemas/SectionEvidence","description":"The evidence value for this brandvisualsystem.","examples":[{}]}},"additionalProperties":false,"type":"object","title":"BrandVisualSystem","description":"Structured brandvisualsystem data exposed by the public API.","examples":[{}]},"BrandVoice":{"properties":{"summary":{"type":"string","maxLength":1500,"title":"Summary","description":"The summary value for this brandvoice.","examples":["Example summary"]},"traits":{"items":{"$ref":"#/components/schemas/VoiceTrait"},"type":"array","maxItems":10,"title":"Traits","description":"The traits value for this brandvoice.","examples":[[{"name":"Example name","description":"Example description"}]]},"principles":{"items":{"type":"string"},"type":"array","maxItems":16,"title":"Principles","description":"The principles value for this brandvoice.","examples":[["Example principles"]]},"writing_rules":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Writing Rules","description":"The writing rules value for this brandvoice.","examples":[["Example writing rules"]]},"preferred_terms":{"items":{"type":"string"},"type":"array","maxItems":30,"title":"Preferred Terms","description":"The preferred terms value for this brandvoice.","examples":[["Example preferred terms"]]},"avoided_terms":{"items":{"type":"string"},"type":"array","maxItems":30,"title":"Avoided Terms","description":"The avoided terms value for this brandvoice.","examples":[["Example avoided terms"]]},"sample_headlines":{"items":{"type":"string"},"type":"array","maxItems":12,"title":"Sample Headlines","description":"The sample headlines value for this brandvoice.","examples":[["Example sample headlines"]]},"sample_calls_to_action":{"items":{"type":"string"},"type":"array","maxItems":12,"title":"Sample Calls To Action","description":"The sample calls to action value for this brandvoice.","examples":[["Example sample calls to action"]]},"evidence":{"$ref":"#/components/schemas/SectionEvidence","description":"The evidence value for this brandvoice.","examples":[{}]}},"additionalProperties":false,"type":"object","required":["summary"],"title":"BrandVoice","description":"Structured brandvoice data exposed by the public API.","examples":[{"summary":"Example summary"}]},"BulletListBlock":{"properties":{"kind":{"type":"string","const":"bullet_list","title":"Kind","description":"The kind value for this bulletlistblock."},"items":{"items":{"items":{"oneOf":[{"$ref":"#/components/schemas/TextInline"},{"$ref":"#/components/schemas/VariableInline"},{"$ref":"#/components/schemas/ConditionInline"}],"discriminator":{"propertyName":"kind","mapping":{"condition":"#/components/schemas/ConditionInline","text":"#/components/schemas/TextInline","variable":"#/components/schemas/VariableInline"}}},"type":"array"},"type":"array","maxItems":10,"minItems":1,"title":"Items","description":"The items value for this bulletlistblock.","examples":[[[{"kind":"text","text":"Example text"}]]]}},"additionalProperties":false,"type":"object","required":["kind","items"],"title":"BulletListBlock","description":"Structured bulletlistblock data exposed by the public API.","examples":[{"kind":"bullet_list","items":[[{"kind":"text","text":"Example text"}]]}]},"CompanyDossierAnalysisPolicyOut":{"properties":{"source_content_classification":{"type":"string","const":"untrusted_data","title":"Source Content Classification","description":"The source content classification value for this companydossieranalysispolicyout."},"embedded_instruction_handling":{"type":"string","const":"ignore","title":"Embedded Instruction Handling","description":"The embedded instruction handling value for this companydossieranalysispolicyout."},"platform_managed_model_only":{"type":"boolean","const":true,"title":"Platform Managed Model Only","description":"The platform managed model only value for this companydossieranalysispolicyout."},"caller_model_accepted":{"type":"boolean","const":false,"title":"Caller Model Accepted","description":"The caller model accepted value for this companydossieranalysispolicyout."},"source_model_binding_carried_forward":{"type":"boolean","const":false,"title":"Source Model Binding Carried Forward","description":"The source model binding carried forward value for this companydossieranalysispolicyout."},"model_allowlist_revalidation_required":{"type":"boolean","const":true,"title":"Model Allowlist Revalidation Required","description":"The model allowlist revalidation required value for this companydossieranalysispolicyout."},"structured_outputs_required":{"type":"boolean","const":true,"title":"Structured Outputs Required","description":"The structured outputs required value for this companydossieranalysispolicyout."},"strict_json_schema_required":{"type":"boolean","const":true,"title":"Strict Json Schema Required","description":"The strict json schema required value for this companydossieranalysispolicyout."},"additional_properties_allowed":{"type":"boolean","const":false,"title":"Additional Properties Allowed","description":"The additional properties allowed value for this companydossieranalysispolicyout."},"model_identity_recording_required":{"type":"boolean","const":true,"title":"Model Identity Recording Required","description":"The model identity recording required value for this companydossieranalysispolicyout."},"prompt_template_version":{"type":"string","const":"company-dossier-2026-07-14","title":"Prompt Template Version","description":"The prompt template version value for this companydossieranalysispolicyout."},"prompt_hash_recording_required":{"type":"boolean","const":true,"title":"Prompt Hash Recording Required","description":"The prompt hash recording required value for this companydossieranalysispolicyout."},"output_schema_hash_recording_required":{"type":"boolean","const":true,"title":"Output Schema Hash Recording Required","description":"The output schema hash recording required value for this companydossieranalysispolicyout."},"source_snapshot_hash_recording_required":{"type":"boolean","const":true,"title":"Source Snapshot Hash Recording Required","description":"The source snapshot hash recording required value for this companydossieranalysispolicyout."},"claim_evidence_binding":{"type":"string","const":"required","title":"Claim Evidence Binding","description":"The claim evidence binding value for this companydossieranalysispolicyout."},"unsupported_claim_handling":{"type":"string","const":"omit","title":"Unsupported Claim Handling","description":"The unsupported claim handling value for this companydossieranalysispolicyout."},"conflicting_evidence_handling":{"type":"string","const":"retain_and_flag","title":"Conflicting Evidence Handling","description":"The conflicting evidence handling value for this companydossieranalysispolicyout."},"model_output_validation":{"type":"string","const":"required","title":"Model Output Validation","description":"The model output validation value for this companydossieranalysispolicyout."},"raw_prompt_logging_allowed":{"type":"boolean","const":false,"title":"Raw Prompt Logging Allowed","description":"The raw prompt logging allowed value for this companydossieranalysispolicyout."},"raw_source_logging_allowed":{"type":"boolean","const":false,"title":"Raw Source Logging Allowed","description":"The raw source logging allowed value for this companydossieranalysispolicyout."},"scoring_or_ranking_allowed":{"type":"boolean","const":false,"title":"Scoring Or Ranking Allowed","description":"The scoring or ranking allowed value for this companydossieranalysispolicyout."},"outreach_generation_allowed":{"type":"boolean","const":false,"title":"Outreach Generation Allowed","description":"The outreach generation allowed value for this companydossieranalysispolicyout."}},"additionalProperties":false,"type":"object","required":["source_content_classification","embedded_instruction_handling","platform_managed_model_only","caller_model_accepted","source_model_binding_carried_forward","model_allowlist_revalidation_required","structured_outputs_required","strict_json_schema_required","additional_properties_allowed","model_identity_recording_required","prompt_template_version","prompt_hash_recording_required","output_schema_hash_recording_required","source_snapshot_hash_recording_required","claim_evidence_binding","unsupported_claim_handling","conflicting_evidence_handling","model_output_validation","raw_prompt_logging_allowed","raw_source_logging_allowed","scoring_or_ranking_allowed","outreach_generation_allowed"],"title":"CompanyDossierAnalysisPolicyOut","description":"Structured companydossieranalysispolicyout data exposed by the public API.","examples":[{"source_content_classification":"untrusted_data","embedded_instruction_handling":"ignore","platform_managed_model_only":true,"caller_model_accepted":false,"source_model_binding_carried_forward":false,"model_allowlist_revalidation_required":true,"structured_outputs_required":true,"strict_json_schema_required":true,"additional_properties_allowed":false,"model_identity_recording_required":true,"prompt_template_version":"company-dossier-2026-07-14","prompt_hash_recording_required":true,"output_schema_hash_recording_required":true,"source_snapshot_hash_recording_required":true,"claim_evidence_binding":"required","unsupported_claim_handling":"omit","conflicting_evidence_handling":"retain_and_flag","model_output_validation":"required","raw_prompt_logging_allowed":false,"raw_source_logging_allowed":false,"scoring_or_ranking_allowed":false,"outreach_generation_allowed":false}]},"CompanyDossierBudgetOut":{"properties":{"maximum_map_requests":{"type":"integer","const":1,"title":"Maximum Map Requests","description":"The maximum map requests value for this companydossierbudgetout."},"maximum_site_pages":{"type":"integer","maximum":20.0,"minimum":1.0,"title":"Maximum Site Pages","description":"The maximum site pages value for this companydossierbudgetout.","examples":[1]},"maximum_search_requests":{"type":"integer","maximum":2.0,"minimum":0.0,"title":"Maximum Search Requests","description":"The maximum search requests value for this companydossierbudgetout.","examples":[0]},"maximum_search_results_per_query":{"type":"integer","maximum":5.0,"minimum":1.0,"title":"Maximum Search Results Per Query","description":"The maximum search results per query value for this companydossierbudgetout.","examples":[1]},"maximum_provider_credits":{"type":"integer","maximum":500.0,"minimum":1.0,"title":"Maximum Provider Credits","description":"The maximum provider credits value for this companydossierbudgetout.","examples":[1]},"maximum_model_requests":{"type":"integer","const":1,"title":"Maximum Model Requests","description":"The maximum model requests value for this companydossierbudgetout."},"maximum_model_input_chars":{"type":"integer","maximum":100000.0,"minimum":1000.0,"title":"Maximum Model Input Chars","description":"The maximum model input chars value for this companydossierbudgetout.","examples":[1000]},"maximum_evidence_items":{"type":"integer","maximum":200.0,"minimum":1.0,"title":"Maximum Evidence Items","description":"The maximum evidence items value for this companydossierbudgetout.","examples":[1]},"maximum_concurrent_requests":{"type":"integer","maximum":4.0,"minimum":1.0,"title":"Maximum Concurrent Requests","description":"The maximum concurrent requests value for this companydossierbudgetout.","examples":[1]},"request_timeout_seconds":{"type":"integer","maximum":60.0,"minimum":5.0,"title":"Request Timeout Seconds","description":"The request timeout seconds value for this companydossierbudgetout.","examples":[5]},"maximum_wall_time_seconds":{"type":"integer","maximum":600.0,"minimum":30.0,"title":"Maximum Wall Time Seconds","description":"The maximum wall time seconds value for this companydossierbudgetout.","examples":[30]},"maximum_total_provider_requests":{"type":"integer","maximum":23.0,"minimum":2.0,"title":"Maximum Total Provider Requests","description":"The maximum total provider requests value for this companydossierbudgetout.","examples":[2]},"maximum_external_search_results":{"type":"integer","maximum":10.0,"minimum":0.0,"title":"Maximum External Search Results","description":"The maximum external search results value for this companydossierbudgetout.","examples":[0]},"provider_credit_budget_is_hard":{"type":"boolean","const":true,"title":"Provider Credit Budget Is Hard","description":"The provider credit budget is hard value for this companydossierbudgetout."},"model_request_budget_is_hard":{"type":"boolean","const":true,"title":"Model Request Budget Is Hard","description":"The model request budget is hard value for this companydossierbudgetout."},"global_request_semaphore_required":{"type":"boolean","const":true,"title":"Global Request Semaphore Required","description":"The global request semaphore required value for this companydossierbudgetout."},"quota_reserved":{"type":"boolean","const":false,"title":"Quota Reserved","description":"The quota reserved value for this companydossierbudgetout."}},"additionalProperties":false,"type":"object","required":["maximum_map_requests","maximum_site_pages","maximum_search_requests","maximum_search_results_per_query","maximum_provider_credits","maximum_model_requests","maximum_model_input_chars","maximum_evidence_items","maximum_concurrent_requests","request_timeout_seconds","maximum_wall_time_seconds","maximum_total_provider_requests","maximum_external_search_results","provider_credit_budget_is_hard","model_request_budget_is_hard","global_request_semaphore_required","quota_reserved"],"title":"CompanyDossierBudgetOut","description":"Structured companydossierbudgetout data exposed by the public API.","examples":[{"maximum_map_requests":1,"maximum_site_pages":1,"maximum_search_requests":0,"maximum_search_results_per_query":1,"maximum_provider_credits":1,"maximum_model_requests":1,"maximum_model_input_chars":1000,"maximum_evidence_items":1,"maximum_concurrent_requests":1,"request_timeout_seconds":5,"maximum_wall_time_seconds":30,"maximum_total_provider_requests":2,"maximum_external_search_results":0,"provider_credit_budget_is_hard":true,"model_request_budget_is_hard":true,"global_request_semaphore_required":true,"quota_reserved":false}]},"CompanyDossierCollectionBudgetIn":{"properties":{"maximum_map_requests":{"type":"integer","const":1,"title":"Maximum Map Requests","description":"The maximum map requests value for this companydossiercollectionbudgetin."},"maximum_site_pages":{"type":"integer","maximum":20.0,"minimum":1.0,"title":"Maximum Site Pages","description":"The maximum site pages value for this companydossiercollectionbudgetin.","examples":[1]},"maximum_search_requests":{"type":"integer","maximum":2.0,"minimum":0.0,"title":"Maximum Search Requests","description":"The maximum search requests value for this companydossiercollectionbudgetin.","examples":[0]},"maximum_search_results_per_query":{"type":"integer","maximum":5.0,"minimum":1.0,"title":"Maximum Search Results Per Query","description":"The maximum search results per query value for this companydossiercollectionbudgetin.","examples":[1]},"maximum_provider_credits":{"type":"integer","maximum":500.0,"minimum":1.0,"title":"Maximum Provider Credits","description":"The maximum provider credits value for this companydossiercollectionbudgetin.","examples":[1]},"maximum_model_requests":{"type":"integer","const":1,"title":"Maximum Model Requests","description":"The maximum model requests value for this companydossiercollectionbudgetin."},"maximum_model_input_chars":{"type":"integer","maximum":100000.0,"minimum":1000.0,"title":"Maximum Model Input Chars","description":"The maximum model input chars value for this companydossiercollectionbudgetin.","examples":[1000]},"maximum_evidence_items":{"type":"integer","maximum":200.0,"minimum":1.0,"title":"Maximum Evidence Items","description":"The maximum evidence items value for this companydossiercollectionbudgetin.","examples":[1]},"maximum_concurrent_requests":{"type":"integer","maximum":4.0,"minimum":1.0,"title":"Maximum Concurrent Requests","description":"The maximum concurrent requests value for this companydossiercollectionbudgetin.","examples":[1]},"request_timeout_seconds":{"type":"integer","maximum":60.0,"minimum":5.0,"title":"Request Timeout Seconds","description":"The request timeout seconds value for this companydossiercollectionbudgetin.","examples":[5]},"maximum_wall_time_seconds":{"type":"integer","maximum":600.0,"minimum":30.0,"title":"Maximum Wall Time Seconds","description":"The maximum wall time seconds value for this companydossiercollectionbudgetin.","examples":[30]}},"additionalProperties":false,"type":"object","required":["maximum_map_requests","maximum_site_pages","maximum_search_requests","maximum_search_results_per_query","maximum_provider_credits","maximum_model_requests","maximum_model_input_chars","maximum_evidence_items","maximum_concurrent_requests","request_timeout_seconds","maximum_wall_time_seconds"],"title":"CompanyDossierCollectionBudgetIn","description":"Hard future-executor ceilings; specification creation reserves no provider quota.","examples":[{"maximum_map_requests":1,"maximum_site_pages":1,"maximum_search_requests":0,"maximum_search_results_per_query":1,"maximum_provider_credits":1,"maximum_model_requests":1,"maximum_model_input_chars":1000,"maximum_evidence_items":1,"maximum_concurrent_requests":1,"request_timeout_seconds":5,"maximum_wall_time_seconds":30}]},"CompanyDossierConnectionIn":{"properties":{"connection_id":{"type":"string","pattern":"^conn_[a-f0-9]{24}$","title":"Connection Id","description":"The connection id value for this companydossierconnectionin.","examples":["conn_aaaaaaaaaaaaaaaaaaaaaaaa"]},"expected_manifest_version":{"type":"string","const":"2026-07-14","title":"Expected Manifest Version","description":"The expected manifest version value for this companydossierconnectionin."},"expected_credentials_version":{"type":"integer","maximum":1000000.0,"minimum":1.0,"title":"Expected Credentials Version","description":"The expected credentials version value for this companydossierconnectionin.","examples":[1]}},"additionalProperties":false,"type":"object","required":["connection_id","expected_manifest_version","expected_credentials_version"],"title":"CompanyDossierConnectionIn","description":"Structured companydossierconnectionin data exposed by the public API.","examples":[{"connection_id":"conn_aaaaaaaaaaaaaaaaaaaaaaaa","expected_manifest_version":"2026-07-14","expected_credentials_version":1}]},"CompanyDossierConnectionOut":{"properties":{"connection_id":{"type":"string","pattern":"^conn_[a-f0-9]{24}$","title":"Connection Id","description":"The connection id value for this companydossierconnectionout.","examples":["conn_aaaaaaaaaaaaaaaaaaaaaaaa"]},"provider_key":{"type":"string","const":"firecrawl","title":"Provider Key","description":"The provider key value for this companydossierconnectionout."},"manifest_version":{"type":"string","const":"2026-07-14","title":"Manifest Version","description":"The manifest version value for this companydossierconnectionout."},"credentials_version":{"type":"integer","minimum":1.0,"title":"Credentials Version","description":"The credentials version value for this companydossierconnectionout.","examples":[1]},"configured_fields":{"items":{"type":"string","const":"api_key"},"type":"array","maxItems":1,"minItems":1,"title":"Configured Fields","description":"The configured fields value for this companydossierconnectionout.","examples":[["api_key"]]},"status":{"type":"string","const":"configured","title":"Status","description":"The status value for this companydossierconnectionout."},"live_verification_status":{"type":"string","const":"not_run","title":"Live Verification Status","description":"The live verification status value for this companydossierconnectionout."},"credentials_decrypted":{"type":"boolean","const":false,"title":"Credentials Decrypted","description":"The credentials decrypted value for this companydossierconnectionout."}},"additionalProperties":false,"type":"object","required":["connection_id","provider_key","manifest_version","credentials_version","configured_fields","status","live_verification_status","credentials_decrypted"],"title":"CompanyDossierConnectionOut","description":"Structured companydossierconnectionout data exposed by the public API.","examples":[{"connection_id":"conn_aaaaaaaaaaaaaaaaaaaaaaaa","provider_key":"firecrawl","manifest_version":"2026-07-14","credentials_version":1,"configured_fields":["api_key"],"status":"configured","live_verification_status":"not_run","credentials_decrypted":false}]},"CompanyDossierPolicyVersion":{"type":"string","enum":["2026-07-15"],"title":"CompanyDossierPolicyVersion","description":"Readable/replayable dossier policies; append versions, never replace them.","examples":["2026-07-15"]},"CompanyDossierProviderOperationOut":{"properties":{"operation":{"type":"string","enum":["map","scrape","search"],"title":"Operation","description":"The operation value for this companydossierprovideroperationout.","examples":["map"]},"method":{"type":"string","const":"POST","title":"Method","description":"The method value for this companydossierprovideroperationout."},"path":{"type":"string","enum":["/v2/map","/v2/scrape","/v2/search"],"title":"Path","description":"The path value for this companydossierprovideroperationout.","examples":["/v2/map"]},"maximum_calls":{"type":"integer","maximum":20.0,"minimum":0.0,"title":"Maximum Calls","description":"The maximum calls value for this companydossierprovideroperationout.","examples":[0]}},"additionalProperties":false,"type":"object","required":["operation","method","path","maximum_calls"],"title":"CompanyDossierProviderOperationOut","description":"Structured companydossierprovideroperationout data exposed by the public API.","examples":[{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0}]},"CompanyDossierProviderPolicyOut":{"properties":{"provider":{"type":"string","const":"firecrawl","title":"Provider","description":"The provider value for this companydossierproviderpolicyout."},"api_version":{"type":"string","const":"v2","title":"Api Version","description":"The api version value for this companydossierproviderpolicyout."},"operations":{"items":{"$ref":"#/components/schemas/CompanyDossierProviderOperationOut"},"type":"array","maxItems":3,"minItems":3,"title":"Operations","description":"The operations value for this companydossierproviderpolicyout.","examples":[[{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0},{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0},{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0}]]},"query_kinds":{"items":{"type":"string","enum":["company_competitors","company_leadership"]},"type":"array","maxItems":2,"title":"Query Kinds","description":"The query kinds value for this companydossierproviderpolicyout.","examples":[["company_competitors"]]},"query_templates_platform_owned":{"type":"boolean","const":true,"title":"Query Templates Platform Owned","description":"The query templates platform owned value for this companydossierproviderpolicyout."},"user_query_accepted":{"type":"boolean","const":false,"title":"User Query Accepted","description":"The user query accepted value for this companydossierproviderpolicyout."},"user_prompt_accepted":{"type":"boolean","const":false,"title":"User Prompt Accepted","description":"The user prompt accepted value for this companydossierproviderpolicyout."},"target_glob_accepted":{"type":"boolean","const":false,"title":"Target Glob Accepted","description":"The target glob accepted value for this companydossierproviderpolicyout."},"site_scope":{"type":"string","const":"same_origin","title":"Site Scope","description":"The site scope value for this companydossierproviderpolicyout."},"include_subdomains":{"type":"boolean","const":false,"title":"Include Subdomains","description":"The include subdomains value for this companydossierproviderpolicyout."},"external_links_followed_from_site":{"type":"boolean","const":false,"title":"External Links Followed From Site","description":"The external links followed from site value for this companydossierproviderpolicyout."},"returned_url_scope_validation_required":{"type":"boolean","const":true,"title":"Returned Url Scope Validation Required","description":"The returned url scope validation required value for this companydossierproviderpolicyout."},"globally_routable_dns_required":{"type":"boolean","const":true,"title":"Globally Routable Dns Required","description":"The globally routable dns required value for this companydossierproviderpolicyout."},"dns_rebinding_protection_required":{"type":"boolean","const":true,"title":"Dns Rebinding Protection Required","description":"The dns rebinding protection required value for this companydossierproviderpolicyout."},"tls_certificate_verification_required":{"type":"boolean","const":true,"title":"Tls Certificate Verification Required","description":"The tls certificate verification required value for this companydossierproviderpolicyout."},"provider_default_skip_tls_overridden":{"type":"boolean","const":true,"title":"Provider Default Skip Tls Overridden","description":"The provider default skip tls overridden value for this companydossierproviderpolicyout."},"headers_or_cookies_forwarded_to_target":{"type":"boolean","const":false,"title":"Headers Or Cookies Forwarded To Target","description":"The headers or cookies forwarded to target value for this companydossierproviderpolicyout."},"browser_actions_allowed":{"type":"boolean","const":false,"title":"Browser Actions Allowed","description":"The browser actions allowed value for this companydossierproviderpolicyout."},"raw_html_requested":{"type":"boolean","const":false,"title":"Raw Html Requested","description":"The raw html requested value for this companydossierproviderpolicyout."},"screenshots_requested":{"type":"boolean","const":false,"title":"Screenshots Requested","description":"The screenshots requested value for this companydossierproviderpolicyout."},"search_result_limit_hard":{"type":"boolean","const":true,"title":"Search Result Limit Hard","description":"The search result limit hard value for this companydossierproviderpolicyout."},"retry_after_honored":{"type":"boolean","const":true,"title":"Retry After Honored","description":"The retry after honored value for this companydossierproviderpolicyout."},"automatic_retry_attempts":{"type":"integer","const":1,"title":"Automatic Retry Attempts","description":"The automatic retry attempts value for this companydossierproviderpolicyout."},"credentials_revalidated_before_each_request":{"type":"boolean","const":true,"title":"Credentials Revalidated Before Each Request","description":"The credentials revalidated before each request value for this companydossierproviderpolicyout."}},"additionalProperties":false,"type":"object","required":["provider","api_version","operations","query_kinds","query_templates_platform_owned","user_query_accepted","user_prompt_accepted","target_glob_accepted","site_scope","include_subdomains","external_links_followed_from_site","returned_url_scope_validation_required","globally_routable_dns_required","dns_rebinding_protection_required","tls_certificate_verification_required","provider_default_skip_tls_overridden","headers_or_cookies_forwarded_to_target","browser_actions_allowed","raw_html_requested","screenshots_requested","search_result_limit_hard","retry_after_honored","automatic_retry_attempts","credentials_revalidated_before_each_request"],"title":"CompanyDossierProviderPolicyOut","description":"Structured companydossierproviderpolicyout data exposed by the public API.","examples":[{"provider":"firecrawl","api_version":"v2","operations":[{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0},{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0},{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0}],"query_kinds":["company_competitors"],"query_templates_platform_owned":true,"user_query_accepted":false,"user_prompt_accepted":false,"target_glob_accepted":false,"site_scope":"same_origin","include_subdomains":false,"external_links_followed_from_site":false,"returned_url_scope_validation_required":true,"globally_routable_dns_required":true,"dns_rebinding_protection_required":true,"tls_certificate_verification_required":true,"provider_default_skip_tls_overridden":true,"headers_or_cookies_forwarded_to_target":false,"browser_actions_allowed":false,"raw_html_requested":false,"screenshots_requested":false,"search_result_limit_hard":true,"retry_after_honored":true,"automatic_retry_attempts":1,"credentials_revalidated_before_each_request":true}]},"CompanyDossierPurpose":{"type":"string","enum":["company_research"],"title":"CompanyDossierPurpose","description":"Structured companydossierpurpose data exposed by the public API.","examples":["company_research"]},"CompanyDossierResultContractOut":{"properties":{"schema_version":{"type":"string","const":"2026-07-15","title":"Schema Version","description":"The schema version value for this companydossierresultcontractout."},"result_shape":{"type":"string","const":"company_dossier_revision_proposal","title":"Result Shape","description":"The result shape value for this companydossierresultcontractout."},"dossier_fields":{"items":{"type":"string"},"type":"array","maxItems":12,"minItems":8,"title":"Dossier Fields","description":"The dossier fields value for this companydossierresultcontractout.","examples":[["Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields"]]},"claim_fields":{"items":{"type":"string"},"type":"array","maxItems":6,"minItems":6,"title":"Claim Fields","description":"The claim fields value for this companydossierresultcontractout.","examples":[["Example claim fields","Example claim fields","Example claim fields","Example claim fields","Example claim fields","Example claim fields"]]},"evidence_fields":{"items":{"type":"string"},"type":"array","maxItems":5,"minItems":5,"title":"Evidence Fields","description":"The evidence fields value for this companydossierresultcontractout.","examples":[["Example evidence fields","Example evidence fields","Example evidence fields","Example evidence fields","Example evidence fields"]]},"citations_required":{"type":"boolean","const":true,"title":"Citations Required","description":"The citations required value for this companydossierresultcontractout."},"leadership_identity_status":{"type":"string","const":"unverified_public_business_claim","title":"Leadership Identity Status","description":"The leadership identity status value for this companydossierresultcontractout."},"contact_coordinates_returned":{"type":"boolean","const":false,"title":"Contact Coordinates Returned","description":"The contact coordinates returned value for this companydossierresultcontractout."},"profile_urls_returned":{"type":"boolean","const":false,"title":"Profile Urls Returned","description":"The profile urls returned value for this companydossierresultcontractout."},"raw_source_urls_returned":{"type":"boolean","const":false,"title":"Raw Source Urls Returned","description":"The raw source urls returned value for this companydossierresultcontractout."},"raw_source_payload_returned":{"type":"boolean","const":false,"title":"Raw Source Payload Returned","description":"The raw source payload returned value for this companydossierresultcontractout."},"executable_markup_returned":{"type":"boolean","const":false,"title":"Executable Markup Returned","description":"The executable markup returned value for this companydossierresultcontractout."},"mermaid_returned":{"type":"boolean","const":false,"title":"Mermaid Returned","description":"The mermaid returned value for this companydossierresultcontractout."},"rendering_available":{"type":"boolean","const":false,"title":"Rendering Available","description":"The rendering available value for this companydossierresultcontractout."}},"additionalProperties":false,"type":"object","required":["schema_version","result_shape","dossier_fields","claim_fields","evidence_fields","citations_required","leadership_identity_status","contact_coordinates_returned","profile_urls_returned","raw_source_urls_returned","raw_source_payload_returned","executable_markup_returned","mermaid_returned","rendering_available"],"title":"CompanyDossierResultContractOut","description":"Structured companydossierresultcontractout data exposed by the public API.","examples":[{"schema_version":"2026-07-15","result_shape":"company_dossier_revision_proposal","dossier_fields":["Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields"],"claim_fields":["Example claim fields","Example claim fields","Example claim fields","Example claim fields","Example claim fields","Example claim fields"],"evidence_fields":["Example evidence fields","Example evidence fields","Example evidence fields","Example evidence fields","Example evidence fields"],"citations_required":true,"leadership_identity_status":"unverified_public_business_claim","contact_coordinates_returned":false,"profile_urls_returned":false,"raw_source_urls_returned":false,"raw_source_payload_returned":false,"executable_markup_returned":false,"mermaid_returned":false,"rendering_available":false}]},"CompanyDossierReviewPolicyOut":{"properties":{"initial_state":{"type":"string","const":"draft_requires_human_review","title":"Initial State","description":"The initial state value for this companydossierreviewpolicyout."},"allowed_decisions":{"items":{"type":"string","enum":["accept","request_revision"]},"type":"array","maxItems":2,"minItems":2,"title":"Allowed Decisions","description":"The allowed decisions value for this companydossierreviewpolicyout.","examples":[["accept","accept"]]},"maximum_revision_rounds":{"type":"integer","const":3,"title":"Maximum Revision Rounds","description":"The maximum revision rounds value for this companydossierreviewpolicyout."},"immutable_revision_hash_required":{"type":"boolean","const":true,"title":"Immutable Revision Hash Required","description":"The immutable revision hash required value for this companydossierreviewpolicyout."},"previous_revision_hash_required":{"type":"boolean","const":true,"title":"Previous Revision Hash Required","description":"The previous revision hash required value for this companydossierreviewpolicyout."},"reviewer_reason_required":{"type":"boolean","const":true,"title":"Reviewer Reason Required","description":"The reviewer reason required value for this companydossierreviewpolicyout."},"acceptance_is_outbound_authorization":{"type":"boolean","const":false,"title":"Acceptance Is Outbound Authorization","description":"The acceptance is outbound authorization value for this companydossierreviewpolicyout."},"acceptance_is_export_authorization":{"type":"boolean","const":false,"title":"Acceptance Is Export Authorization","description":"The acceptance is export authorization value for this companydossierreviewpolicyout."},"unlimited_revision_loop_allowed":{"type":"boolean","const":false,"title":"Unlimited Revision Loop Allowed","description":"The unlimited revision loop allowed value for this companydossierreviewpolicyout."}},"additionalProperties":false,"type":"object","required":["initial_state","allowed_decisions","maximum_revision_rounds","immutable_revision_hash_required","previous_revision_hash_required","reviewer_reason_required","acceptance_is_outbound_authorization","acceptance_is_export_authorization","unlimited_revision_loop_allowed"],"title":"CompanyDossierReviewPolicyOut","description":"Structured companydossierreviewpolicyout data exposed by the public API.","examples":[{"initial_state":"draft_requires_human_review","allowed_decisions":["accept","accept"],"maximum_revision_rounds":3,"immutable_revision_hash_required":true,"previous_revision_hash_required":true,"reviewer_reason_required":true,"acceptance_is_outbound_authorization":false,"acceptance_is_export_authorization":false,"unlimited_revision_loop_allowed":false}]},"CompanyDossierSchemaVersion":{"type":"string","enum":["2026-07-15"],"title":"CompanyDossierSchemaVersion","description":"Readable historical response schemas; append versions, never replace them.","examples":["2026-07-15"]},"CompanyDossierSection":{"type":"string","enum":["company_profile","commercial_signals","competitors","leadership","market_position","offerings"],"title":"CompanyDossierSection","description":"Structured companydossiersection data exposed by the public API.","examples":["company_profile"]},"CompanyDossierSectionSpecOut":{"properties":{"section":{"$ref":"#/components/schemas/CompanyDossierSection","description":"The section value for this companydossiersectionspecout.","examples":["company_profile"]},"description":{"type":"string","maxLength":500,"minLength":3,"title":"Description","description":"The description value for this companydossiersectionspecout.","examples":["Example description"]},"claim_types":{"items":{"type":"string"},"type":"array","maxItems":8,"minItems":1,"title":"Claim Types","description":"The claim types value for this companydossiersectionspecout.","examples":[["Example claim types"]]},"maximum_evidence_age_days":{"type":"integer","maximum":3650.0,"minimum":1.0,"title":"Maximum Evidence Age Days","description":"The maximum evidence age days value for this companydossiersectionspecout.","examples":[1]},"minimum_evidence_items_per_claim":{"type":"integer","const":1,"title":"Minimum Evidence Items Per Claim","description":"The minimum evidence items per claim value for this companydossiersectionspecout."},"unsupported_behavior":{"type":"string","const":"omit","title":"Unsupported Behavior","description":"The unsupported behavior value for this companydossiersectionspecout."}},"additionalProperties":false,"type":"object","required":["section","description","claim_types","maximum_evidence_age_days","minimum_evidence_items_per_claim","unsupported_behavior"],"title":"CompanyDossierSectionSpecOut","description":"Structured companydossiersectionspecout data exposed by the public API.","examples":[{"section":"company_profile","description":"Example description","claim_types":["Example claim types"],"maximum_evidence_age_days":1,"minimum_evidence_items_per_claim":1,"unsupported_behavior":"omit"}]},"CompanyDossierSpecificationCreateIn":{"properties":{"key":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","title":"Key","description":"The key value for this companydossierspecificationcreatein.","examples":["example-key"]},"target":{"$ref":"#/components/schemas/CompanyDossierTargetIn","description":"The target value for this companydossierspecificationcreatein.","examples":[{"domain":"Example domain"}]},"connection":{"$ref":"#/components/schemas/CompanyDossierConnectionIn","description":"The connection value for this companydossierspecificationcreatein.","examples":[{"connection_id":"conn_aaaaaaaaaaaaaaaaaaaaaaaa","expected_manifest_version":"2026-07-14","expected_credentials_version":1}]},"sections":{"items":{"$ref":"#/components/schemas/CompanyDossierSection"},"type":"array","maxItems":6,"minItems":1,"title":"Sections","description":"The sections value for this companydossierspecificationcreatein.","examples":[["company_profile"]]},"collection_budget":{"$ref":"#/components/schemas/CompanyDossierCollectionBudgetIn","description":"The collection budget value for this companydossierspecificationcreatein.","examples":[{"maximum_map_requests":1,"maximum_site_pages":1,"maximum_search_requests":0,"maximum_search_results_per_query":1,"maximum_provider_credits":1,"maximum_model_requests":1,"maximum_model_input_chars":1000,"maximum_evidence_items":1,"maximum_concurrent_requests":1,"request_timeout_seconds":5,"maximum_wall_time_seconds":30}]},"purpose":{"type":"string","const":"company_research","title":"Purpose","description":"The purpose value for this companydossierspecificationcreatein."},"expected_policy_version":{"$ref":"#/components/schemas/CompanyDossierPolicyVersion","description":"The expected policy version value for this companydossierspecificationcreatein.","examples":["2026-07-15"]},"reason":{"type":"string","maxLength":500,"minLength":3,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"Reason","description":"The reason value for this companydossierspecificationcreatein.","examples":["Example value"]}},"additionalProperties":false,"type":"object","required":["key","target","connection","sections","collection_budget","purpose","expected_policy_version","reason"],"title":"CompanyDossierSpecificationCreateIn","description":"Freeze company research intent without accepting URLs, prompts, source rows, or keys.","examples":[{"key":"example-key","target":{"domain":"Example domain"},"connection":{"connection_id":"conn_aaaaaaaaaaaaaaaaaaaaaaaa","expected_manifest_version":"2026-07-14","expected_credentials_version":1},"sections":["company_profile"],"collection_budget":{"maximum_map_requests":1,"maximum_site_pages":1,"maximum_search_requests":0,"maximum_search_results_per_query":1,"maximum_provider_credits":1,"maximum_model_requests":1,"maximum_model_input_chars":1000,"maximum_evidence_items":1,"maximum_concurrent_requests":1,"request_timeout_seconds":5,"maximum_wall_time_seconds":30},"purpose":"company_research","expected_policy_version":"2026-07-15","reason":"Example value"}]},"CompanyDossierSpecificationListOut":{"properties":{"schema_version":{"$ref":"#/components/schemas/CompanyDossierSchemaVersion","description":"The schema version value for this companydossierspecificationlistout.","examples":["2026-07-15"]},"availability":{"type":"string","const":"contract_only","title":"Availability","description":"The availability value for this companydossierspecificationlistout."},"specifications":{"items":{"$ref":"#/components/schemas/CompanyDossierSpecificationOut"},"type":"array","title":"Specifications","description":"The specifications value for this companydossierspecificationlistout.","examples":[[{"schema_version":"2026-07-15","status":"specified","availability":"contract_only","id":"companydossier_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","target":{"domain":"Example domain","origin":"https://example.com","root_path":"/","arbitrary_url_accepted":false,"public_dns_preflight_required":true},"connection":{"connection_id":"conn_aaaaaaaaaaaaaaaaaaaaaaaa","provider_key":"firecrawl","manifest_version":"2026-07-14","credentials_version":1,"configured_fields":["api_key"],"status":"configured","live_verification_status":"not_run","credentials_decrypted":false},"sections":["company_profile"],"section_specs":[{"section":"company_profile","description":"Example description","claim_types":["Example claim types"],"maximum_evidence_age_days":1,"minimum_evidence_items_per_claim":1,"unsupported_behavior":"omit"}],"contains_personal_data":true,"collection_budget":{"maximum_map_requests":1,"maximum_site_pages":1,"maximum_search_requests":0,"maximum_search_results_per_query":1,"maximum_provider_credits":1,"maximum_model_requests":1,"maximum_model_input_chars":1000,"maximum_evidence_items":1,"maximum_concurrent_requests":1,"request_timeout_seconds":5,"maximum_wall_time_seconds":30,"maximum_total_provider_requests":2,"maximum_external_search_results":0,"provider_credit_budget_is_hard":true,"model_request_budget_is_hard":true,"global_request_semaphore_required":true,"quota_reserved":false},"provider_policy":{"provider":"firecrawl","api_version":"v2","operations":[{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0},{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0},{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0}],"query_kinds":["company_competitors"],"query_templates_platform_owned":true,"user_query_accepted":false,"user_prompt_accepted":false,"target_glob_accepted":false,"site_scope":"same_origin","include_subdomains":false,"external_links_followed_from_site":false,"returned_url_scope_validation_required":true,"globally_routable_dns_required":true,"dns_rebinding_protection_required":true,"tls_certificate_verification_required":true,"provider_default_skip_tls_overridden":true,"headers_or_cookies_forwarded_to_target":false,"browser_actions_allowed":false,"raw_html_requested":false,"screenshots_requested":false,"search_result_limit_hard":true,"retry_after_honored":true,"automatic_retry_attempts":1,"credentials_revalidated_before_each_request":true},"analysis_policy":{"source_content_classification":"untrusted_data","embedded_instruction_handling":"ignore","platform_managed_model_only":true,"caller_model_accepted":false,"source_model_binding_carried_forward":false,"model_allowlist_revalidation_required":true,"structured_outputs_required":true,"strict_json_schema_required":true,"additional_properties_allowed":false,"model_identity_recording_required":true,"prompt_template_version":"company-dossier-2026-07-14","prompt_hash_recording_required":true,"output_schema_hash_recording_required":true,"source_snapshot_hash_recording_required":true,"claim_evidence_binding":"required","unsupported_claim_handling":"omit","conflicting_evidence_handling":"retain_and_flag","model_output_validation":"required","raw_prompt_logging_allowed":false,"raw_source_logging_allowed":false,"scoring_or_ranking_allowed":false,"outreach_generation_allowed":false},"review_policy":{"initial_state":"draft_requires_human_review","allowed_decisions":["accept","accept"],"maximum_revision_rounds":3,"immutable_revision_hash_required":true,"previous_revision_hash_required":true,"reviewer_reason_required":true,"acceptance_is_outbound_authorization":false,"acceptance_is_export_authorization":false,"unlimited_revision_loop_allowed":false},"result_contract":{"schema_version":"2026-07-15","result_shape":"company_dossier_revision_proposal","dossier_fields":["Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields"],"claim_fields":["Example claim fields","Example claim fields","Example claim fields","Example claim fields","Example claim fields","Example claim fields"],"evidence_fields":["Example evidence fields","Example evidence fields","Example evidence fields","Example evidence fields","Example evidence fields"],"citations_required":true,"leadership_identity_status":"unverified_public_business_claim","contact_coordinates_returned":false,"profile_urls_returned":false,"raw_source_urls_returned":false,"raw_source_payload_returned":false,"executable_markup_returned":false,"mermaid_returned":false,"rendering_available":false},"purpose":"company_research","policy_version":"2026-07-15","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"provider_requests_made":0,"provider_credits_spent":0,"model_requests_made":0,"network_requests_made":0,"browser_requests_made":0,"map_requests_made":0,"scrape_requests_made":0,"search_requests_made":0,"pages_fetched":0,"search_results_read":0,"source_records_read":0,"source_content_stored":false,"raw_provider_payload_stored":false,"arbitrary_url_accepted":false,"arbitrary_prompt_accepted":false,"source_instructions_followed":false,"dossier_revisions_created":0,"dossier_claims_created":0,"evidence_items_created":0,"human_reviews_recorded":0,"documents_rendered":0,"exports_created":0,"contact_coordinates_created":0,"outreach_drafts_created":0,"message_send_authorized":false,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}]]},"total":{"type":"integer","maximum":1000.0,"minimum":0.0,"title":"Total","description":"The total value for this companydossierspecificationlistout.","examples":[0]},"limit":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Limit","description":"The limit value for this companydossierspecificationlistout.","examples":[1]},"offset":{"type":"integer","maximum":10000.0,"minimum":0.0,"title":"Offset","description":"The offset value for this companydossierspecificationlistout.","examples":[0]},"execution_available":{"type":"boolean","const":false,"title":"Execution Available","description":"The execution available value for this companydossierspecificationlistout."},"provider_requests_made":{"type":"integer","const":0,"title":"Provider Requests Made","description":"The provider requests made value for this companydossierspecificationlistout."},"model_requests_made":{"type":"integer","const":0,"title":"Model Requests Made","description":"The model requests made value for this companydossierspecificationlistout."},"dossier_revisions_created":{"type":"integer","const":0,"title":"Dossier Revisions Created","description":"The dossier revisions created value for this companydossierspecificationlistout."}},"additionalProperties":false,"type":"object","required":["schema_version","availability","specifications","total","limit","offset","execution_available","provider_requests_made","model_requests_made","dossier_revisions_created"],"title":"CompanyDossierSpecificationListOut","description":"Structured companydossierspecificationlistout data exposed by the public API.","examples":[{"schema_version":"2026-07-15","availability":"contract_only","specifications":[{"schema_version":"2026-07-15","status":"specified","availability":"contract_only","id":"companydossier_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","target":{"domain":"Example domain","origin":"https://example.com","root_path":"/","arbitrary_url_accepted":false,"public_dns_preflight_required":true},"connection":{"connection_id":"conn_aaaaaaaaaaaaaaaaaaaaaaaa","provider_key":"firecrawl","manifest_version":"2026-07-14","credentials_version":1,"configured_fields":["api_key"],"status":"configured","live_verification_status":"not_run","credentials_decrypted":false},"sections":["company_profile"],"section_specs":[{"section":"company_profile","description":"Example description","claim_types":["Example claim types"],"maximum_evidence_age_days":1,"minimum_evidence_items_per_claim":1,"unsupported_behavior":"omit"}],"contains_personal_data":true,"collection_budget":{"maximum_map_requests":1,"maximum_site_pages":1,"maximum_search_requests":0,"maximum_search_results_per_query":1,"maximum_provider_credits":1,"maximum_model_requests":1,"maximum_model_input_chars":1000,"maximum_evidence_items":1,"maximum_concurrent_requests":1,"request_timeout_seconds":5,"maximum_wall_time_seconds":30,"maximum_total_provider_requests":2,"maximum_external_search_results":0,"provider_credit_budget_is_hard":true,"model_request_budget_is_hard":true,"global_request_semaphore_required":true,"quota_reserved":false},"provider_policy":{"provider":"firecrawl","api_version":"v2","operations":[{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0},{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0},{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0}],"query_kinds":["company_competitors"],"query_templates_platform_owned":true,"user_query_accepted":false,"user_prompt_accepted":false,"target_glob_accepted":false,"site_scope":"same_origin","include_subdomains":false,"external_links_followed_from_site":false,"returned_url_scope_validation_required":true,"globally_routable_dns_required":true,"dns_rebinding_protection_required":true,"tls_certificate_verification_required":true,"provider_default_skip_tls_overridden":true,"headers_or_cookies_forwarded_to_target":false,"browser_actions_allowed":false,"raw_html_requested":false,"screenshots_requested":false,"search_result_limit_hard":true,"retry_after_honored":true,"automatic_retry_attempts":1,"credentials_revalidated_before_each_request":true},"analysis_policy":{"source_content_classification":"untrusted_data","embedded_instruction_handling":"ignore","platform_managed_model_only":true,"caller_model_accepted":false,"source_model_binding_carried_forward":false,"model_allowlist_revalidation_required":true,"structured_outputs_required":true,"strict_json_schema_required":true,"additional_properties_allowed":false,"model_identity_recording_required":true,"prompt_template_version":"company-dossier-2026-07-14","prompt_hash_recording_required":true,"output_schema_hash_recording_required":true,"source_snapshot_hash_recording_required":true,"claim_evidence_binding":"required","unsupported_claim_handling":"omit","conflicting_evidence_handling":"retain_and_flag","model_output_validation":"required","raw_prompt_logging_allowed":false,"raw_source_logging_allowed":false,"scoring_or_ranking_allowed":false,"outreach_generation_allowed":false},"review_policy":{"initial_state":"draft_requires_human_review","allowed_decisions":["accept","accept"],"maximum_revision_rounds":3,"immutable_revision_hash_required":true,"previous_revision_hash_required":true,"reviewer_reason_required":true,"acceptance_is_outbound_authorization":false,"acceptance_is_export_authorization":false,"unlimited_revision_loop_allowed":false},"result_contract":{"schema_version":"2026-07-15","result_shape":"company_dossier_revision_proposal","dossier_fields":["Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields"],"claim_fields":["Example claim fields","Example claim fields","Example claim fields","Example claim fields","Example claim fields","Example claim fields"],"evidence_fields":["Example evidence fields","Example evidence fields","Example evidence fields","Example evidence fields","Example evidence fields"],"citations_required":true,"leadership_identity_status":"unverified_public_business_claim","contact_coordinates_returned":false,"profile_urls_returned":false,"raw_source_urls_returned":false,"raw_source_payload_returned":false,"executable_markup_returned":false,"mermaid_returned":false,"rendering_available":false},"purpose":"company_research","policy_version":"2026-07-15","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"provider_requests_made":0,"provider_credits_spent":0,"model_requests_made":0,"network_requests_made":0,"browser_requests_made":0,"map_requests_made":0,"scrape_requests_made":0,"search_requests_made":0,"pages_fetched":0,"search_results_read":0,"source_records_read":0,"source_content_stored":false,"raw_provider_payload_stored":false,"arbitrary_url_accepted":false,"arbitrary_prompt_accepted":false,"source_instructions_followed":false,"dossier_revisions_created":0,"dossier_claims_created":0,"evidence_items_created":0,"human_reviews_recorded":0,"documents_rendered":0,"exports_created":0,"contact_coordinates_created":0,"outreach_drafts_created":0,"message_send_authorized":false,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}],"total":0,"limit":1,"offset":0,"execution_available":false,"provider_requests_made":0,"model_requests_made":0,"dossier_revisions_created":0}]},"CompanyDossierSpecificationOut":{"properties":{"schema_version":{"$ref":"#/components/schemas/CompanyDossierSchemaVersion","description":"The schema version value for this companydossierspecificationout.","examples":["2026-07-15"]},"status":{"type":"string","const":"specified","title":"Status","description":"The status value for this companydossierspecificationout."},"availability":{"type":"string","const":"contract_only","title":"Availability","description":"The availability value for this companydossierspecificationout."},"id":{"type":"string","pattern":"^companydossier_[a-f0-9]{24}$","title":"Id","description":"The id value for this companydossierspecificationout.","examples":["companydossier_aaaaaaaaaaaaaaaaaaaaaaaa"]},"idempotent_replay":{"type":"boolean","title":"Idempotent Replay","description":"The idempotent replay value for this companydossierspecificationout.","examples":[true]},"key":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","title":"Key","description":"The key value for this companydossierspecificationout.","examples":["example-key"]},"project_id":{"type":"string","pattern":"^proj_[a-f0-9]{24}$","title":"Project Id","description":"The project id value for this companydossierspecificationout.","examples":["proj_aaaaaaaaaaaaaaaaaaaaaaaa"]},"environment":{"type":"string","enum":["live","test"],"title":"Environment","description":"The environment value for this companydossierspecificationout.","examples":["live"]},"target":{"$ref":"#/components/schemas/CompanyDossierTargetOut","description":"The target value for this companydossierspecificationout.","examples":[{"domain":"Example domain","origin":"https://example.com","root_path":"/","arbitrary_url_accepted":false,"public_dns_preflight_required":true}]},"connection":{"$ref":"#/components/schemas/CompanyDossierConnectionOut","description":"The connection value for this companydossierspecificationout.","examples":[{"connection_id":"conn_aaaaaaaaaaaaaaaaaaaaaaaa","provider_key":"firecrawl","manifest_version":"2026-07-14","credentials_version":1,"configured_fields":["api_key"],"status":"configured","live_verification_status":"not_run","credentials_decrypted":false}]},"sections":{"items":{"$ref":"#/components/schemas/CompanyDossierSection"},"type":"array","maxItems":6,"minItems":1,"title":"Sections","description":"The sections value for this companydossierspecificationout.","examples":[["company_profile"]]},"section_specs":{"items":{"$ref":"#/components/schemas/CompanyDossierSectionSpecOut"},"type":"array","maxItems":6,"minItems":1,"title":"Section Specs","description":"The section specs value for this companydossierspecificationout.","examples":[[{"section":"company_profile","description":"Example description","claim_types":["Example claim types"],"maximum_evidence_age_days":1,"minimum_evidence_items_per_claim":1,"unsupported_behavior":"omit"}]]},"contains_personal_data":{"type":"boolean","title":"Contains Personal Data","description":"The contains personal data value for this companydossierspecificationout.","examples":[true]},"collection_budget":{"$ref":"#/components/schemas/CompanyDossierBudgetOut","description":"The collection budget value for this companydossierspecificationout.","examples":[{"maximum_map_requests":1,"maximum_site_pages":1,"maximum_search_requests":0,"maximum_search_results_per_query":1,"maximum_provider_credits":1,"maximum_model_requests":1,"maximum_model_input_chars":1000,"maximum_evidence_items":1,"maximum_concurrent_requests":1,"request_timeout_seconds":5,"maximum_wall_time_seconds":30,"maximum_total_provider_requests":2,"maximum_external_search_results":0,"provider_credit_budget_is_hard":true,"model_request_budget_is_hard":true,"global_request_semaphore_required":true,"quota_reserved":false}]},"provider_policy":{"$ref":"#/components/schemas/CompanyDossierProviderPolicyOut","description":"The provider policy value for this companydossierspecificationout.","examples":[{"provider":"firecrawl","api_version":"v2","operations":[{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0},{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0},{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0}],"query_kinds":["company_competitors"],"query_templates_platform_owned":true,"user_query_accepted":false,"user_prompt_accepted":false,"target_glob_accepted":false,"site_scope":"same_origin","include_subdomains":false,"external_links_followed_from_site":false,"returned_url_scope_validation_required":true,"globally_routable_dns_required":true,"dns_rebinding_protection_required":true,"tls_certificate_verification_required":true,"provider_default_skip_tls_overridden":true,"headers_or_cookies_forwarded_to_target":false,"browser_actions_allowed":false,"raw_html_requested":false,"screenshots_requested":false,"search_result_limit_hard":true,"retry_after_honored":true,"automatic_retry_attempts":1,"credentials_revalidated_before_each_request":true}]},"analysis_policy":{"$ref":"#/components/schemas/CompanyDossierAnalysisPolicyOut","description":"The analysis policy value for this companydossierspecificationout.","examples":[{"source_content_classification":"untrusted_data","embedded_instruction_handling":"ignore","platform_managed_model_only":true,"caller_model_accepted":false,"source_model_binding_carried_forward":false,"model_allowlist_revalidation_required":true,"structured_outputs_required":true,"strict_json_schema_required":true,"additional_properties_allowed":false,"model_identity_recording_required":true,"prompt_template_version":"company-dossier-2026-07-14","prompt_hash_recording_required":true,"output_schema_hash_recording_required":true,"source_snapshot_hash_recording_required":true,"claim_evidence_binding":"required","unsupported_claim_handling":"omit","conflicting_evidence_handling":"retain_and_flag","model_output_validation":"required","raw_prompt_logging_allowed":false,"raw_source_logging_allowed":false,"scoring_or_ranking_allowed":false,"outreach_generation_allowed":false}]},"review_policy":{"$ref":"#/components/schemas/CompanyDossierReviewPolicyOut","description":"The review policy value for this companydossierspecificationout.","examples":[{"initial_state":"draft_requires_human_review","allowed_decisions":["accept","accept"],"maximum_revision_rounds":3,"immutable_revision_hash_required":true,"previous_revision_hash_required":true,"reviewer_reason_required":true,"acceptance_is_outbound_authorization":false,"acceptance_is_export_authorization":false,"unlimited_revision_loop_allowed":false}]},"result_contract":{"$ref":"#/components/schemas/CompanyDossierResultContractOut","description":"The result contract value for this companydossierspecificationout.","examples":[{"schema_version":"2026-07-15","result_shape":"company_dossier_revision_proposal","dossier_fields":["Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields"],"claim_fields":["Example claim fields","Example claim fields","Example claim fields","Example claim fields","Example claim fields","Example claim fields"],"evidence_fields":["Example evidence fields","Example evidence fields","Example evidence fields","Example evidence fields","Example evidence fields"],"citations_required":true,"leadership_identity_status":"unverified_public_business_claim","contact_coordinates_returned":false,"profile_urls_returned":false,"raw_source_urls_returned":false,"raw_source_payload_returned":false,"executable_markup_returned":false,"mermaid_returned":false,"rendering_available":false}]},"purpose":{"$ref":"#/components/schemas/CompanyDossierPurpose","description":"The purpose value for this companydossierspecificationout.","examples":["company_research"]},"policy_version":{"$ref":"#/components/schemas/CompanyDossierPolicyVersion","description":"The policy version value for this companydossierspecificationout.","examples":["2026-07-15"]},"specification_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Specification Hash","description":"The specification hash value for this companydossierspecificationout.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"reason":{"type":"string","maxLength":500,"minLength":3,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"Reason","description":"The reason value for this companydossierspecificationout.","examples":["Example value"]},"execution_available":{"type":"boolean","const":false,"title":"Execution Available","description":"The execution available value for this companydossierspecificationout."},"execution_authorized":{"type":"boolean","const":false,"title":"Execution Authorized","description":"The execution authorized value for this companydossierspecificationout."},"provider_requests_made":{"type":"integer","const":0,"title":"Provider Requests Made","description":"The provider requests made value for this companydossierspecificationout."},"provider_credits_spent":{"type":"integer","const":0,"title":"Provider Credits Spent","description":"The provider credits spent value for this companydossierspecificationout."},"model_requests_made":{"type":"integer","const":0,"title":"Model Requests Made","description":"The model requests made value for this companydossierspecificationout."},"network_requests_made":{"type":"integer","const":0,"title":"Network Requests Made","description":"The network requests made value for this companydossierspecificationout."},"browser_requests_made":{"type":"integer","const":0,"title":"Browser Requests Made","description":"The browser requests made value for this companydossierspecificationout."},"map_requests_made":{"type":"integer","const":0,"title":"Map Requests Made","description":"The map requests made value for this companydossierspecificationout."},"scrape_requests_made":{"type":"integer","const":0,"title":"Scrape Requests Made","description":"The scrape requests made value for this companydossierspecificationout."},"search_requests_made":{"type":"integer","const":0,"title":"Search Requests Made","description":"The search requests made value for this companydossierspecificationout."},"pages_fetched":{"type":"integer","const":0,"title":"Pages Fetched","description":"The pages fetched value for this companydossierspecificationout."},"search_results_read":{"type":"integer","const":0,"title":"Search Results Read","description":"The search results read value for this companydossierspecificationout."},"source_records_read":{"type":"integer","const":0,"title":"Source Records Read","description":"The source records read value for this companydossierspecificationout."},"source_content_stored":{"type":"boolean","const":false,"title":"Source Content Stored","description":"The source content stored value for this companydossierspecificationout."},"raw_provider_payload_stored":{"type":"boolean","const":false,"title":"Raw Provider Payload Stored","description":"The raw provider payload stored value for this companydossierspecificationout."},"arbitrary_url_accepted":{"type":"boolean","const":false,"title":"Arbitrary Url Accepted","description":"The arbitrary url accepted value for this companydossierspecificationout."},"arbitrary_prompt_accepted":{"type":"boolean","const":false,"title":"Arbitrary Prompt Accepted","description":"The arbitrary prompt accepted value for this companydossierspecificationout."},"source_instructions_followed":{"type":"boolean","const":false,"title":"Source Instructions Followed","description":"The source instructions followed value for this companydossierspecificationout."},"dossier_revisions_created":{"type":"integer","const":0,"title":"Dossier Revisions Created","description":"The dossier revisions created value for this companydossierspecificationout."},"dossier_claims_created":{"type":"integer","const":0,"title":"Dossier Claims Created","description":"The dossier claims created value for this companydossierspecificationout."},"evidence_items_created":{"type":"integer","const":0,"title":"Evidence Items Created","description":"The evidence items created value for this companydossierspecificationout."},"human_reviews_recorded":{"type":"integer","const":0,"title":"Human Reviews Recorded","description":"The human reviews recorded value for this companydossierspecificationout."},"documents_rendered":{"type":"integer","const":0,"title":"Documents Rendered","description":"The documents rendered value for this companydossierspecificationout."},"exports_created":{"type":"integer","const":0,"title":"Exports Created","description":"The exports created value for this companydossierspecificationout."},"contact_coordinates_created":{"type":"integer","const":0,"title":"Contact Coordinates Created","description":"The contact coordinates created value for this companydossierspecificationout."},"outreach_drafts_created":{"type":"integer","const":0,"title":"Outreach Drafts Created","description":"The outreach drafts created value for this companydossierspecificationout."},"message_send_authorized":{"type":"boolean","const":false,"title":"Message Send Authorized","description":"The message send authorized value for this companydossierspecificationout."},"export_authorized":{"type":"boolean","const":false,"title":"Export Authorized","description":"The export authorized value for this companydossierspecificationout."},"outbound_authorized":{"type":"boolean","const":false,"title":"Outbound Authorized","description":"The outbound authorized value for this companydossierspecificationout."},"crm_mutation_authorized":{"type":"boolean","const":false,"title":"Crm Mutation Authorized","description":"The crm mutation authorized value for this companydossierspecificationout."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"The created at value for this companydossierspecificationout.","examples":["2026-07-16T00:00:00Z"]}},"additionalProperties":false,"type":"object","required":["schema_version","status","availability","id","idempotent_replay","key","project_id","environment","target","connection","sections","section_specs","contains_personal_data","collection_budget","provider_policy","analysis_policy","review_policy","result_contract","purpose","policy_version","specification_hash","reason","execution_available","execution_authorized","provider_requests_made","provider_credits_spent","model_requests_made","network_requests_made","browser_requests_made","map_requests_made","scrape_requests_made","search_requests_made","pages_fetched","search_results_read","source_records_read","source_content_stored","raw_provider_payload_stored","arbitrary_url_accepted","arbitrary_prompt_accepted","source_instructions_followed","dossier_revisions_created","dossier_claims_created","evidence_items_created","human_reviews_recorded","documents_rendered","exports_created","contact_coordinates_created","outreach_drafts_created","message_send_authorized","export_authorized","outbound_authorized","crm_mutation_authorized","created_at"],"title":"CompanyDossierSpecificationOut","description":"Structured companydossierspecificationout data exposed by the public API.","examples":[{"schema_version":"2026-07-15","status":"specified","availability":"contract_only","id":"companydossier_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","target":{"domain":"Example domain","origin":"https://example.com","root_path":"/","arbitrary_url_accepted":false,"public_dns_preflight_required":true},"connection":{"connection_id":"conn_aaaaaaaaaaaaaaaaaaaaaaaa","provider_key":"firecrawl","manifest_version":"2026-07-14","credentials_version":1,"configured_fields":["api_key"],"status":"configured","live_verification_status":"not_run","credentials_decrypted":false},"sections":["company_profile"],"section_specs":[{"section":"company_profile","description":"Example description","claim_types":["Example claim types"],"maximum_evidence_age_days":1,"minimum_evidence_items_per_claim":1,"unsupported_behavior":"omit"}],"contains_personal_data":true,"collection_budget":{"maximum_map_requests":1,"maximum_site_pages":1,"maximum_search_requests":0,"maximum_search_results_per_query":1,"maximum_provider_credits":1,"maximum_model_requests":1,"maximum_model_input_chars":1000,"maximum_evidence_items":1,"maximum_concurrent_requests":1,"request_timeout_seconds":5,"maximum_wall_time_seconds":30,"maximum_total_provider_requests":2,"maximum_external_search_results":0,"provider_credit_budget_is_hard":true,"model_request_budget_is_hard":true,"global_request_semaphore_required":true,"quota_reserved":false},"provider_policy":{"provider":"firecrawl","api_version":"v2","operations":[{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0},{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0},{"operation":"map","method":"POST","path":"/v2/map","maximum_calls":0}],"query_kinds":["company_competitors"],"query_templates_platform_owned":true,"user_query_accepted":false,"user_prompt_accepted":false,"target_glob_accepted":false,"site_scope":"same_origin","include_subdomains":false,"external_links_followed_from_site":false,"returned_url_scope_validation_required":true,"globally_routable_dns_required":true,"dns_rebinding_protection_required":true,"tls_certificate_verification_required":true,"provider_default_skip_tls_overridden":true,"headers_or_cookies_forwarded_to_target":false,"browser_actions_allowed":false,"raw_html_requested":false,"screenshots_requested":false,"search_result_limit_hard":true,"retry_after_honored":true,"automatic_retry_attempts":1,"credentials_revalidated_before_each_request":true},"analysis_policy":{"source_content_classification":"untrusted_data","embedded_instruction_handling":"ignore","platform_managed_model_only":true,"caller_model_accepted":false,"source_model_binding_carried_forward":false,"model_allowlist_revalidation_required":true,"structured_outputs_required":true,"strict_json_schema_required":true,"additional_properties_allowed":false,"model_identity_recording_required":true,"prompt_template_version":"company-dossier-2026-07-14","prompt_hash_recording_required":true,"output_schema_hash_recording_required":true,"source_snapshot_hash_recording_required":true,"claim_evidence_binding":"required","unsupported_claim_handling":"omit","conflicting_evidence_handling":"retain_and_flag","model_output_validation":"required","raw_prompt_logging_allowed":false,"raw_source_logging_allowed":false,"scoring_or_ranking_allowed":false,"outreach_generation_allowed":false},"review_policy":{"initial_state":"draft_requires_human_review","allowed_decisions":["accept","accept"],"maximum_revision_rounds":3,"immutable_revision_hash_required":true,"previous_revision_hash_required":true,"reviewer_reason_required":true,"acceptance_is_outbound_authorization":false,"acceptance_is_export_authorization":false,"unlimited_revision_loop_allowed":false},"result_contract":{"schema_version":"2026-07-15","result_shape":"company_dossier_revision_proposal","dossier_fields":["Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields","Example dossier fields"],"claim_fields":["Example claim fields","Example claim fields","Example claim fields","Example claim fields","Example claim fields","Example claim fields"],"evidence_fields":["Example evidence fields","Example evidence fields","Example evidence fields","Example evidence fields","Example evidence fields"],"citations_required":true,"leadership_identity_status":"unverified_public_business_claim","contact_coordinates_returned":false,"profile_urls_returned":false,"raw_source_urls_returned":false,"raw_source_payload_returned":false,"executable_markup_returned":false,"mermaid_returned":false,"rendering_available":false},"purpose":"company_research","policy_version":"2026-07-15","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"provider_requests_made":0,"provider_credits_spent":0,"model_requests_made":0,"network_requests_made":0,"browser_requests_made":0,"map_requests_made":0,"scrape_requests_made":0,"search_requests_made":0,"pages_fetched":0,"search_results_read":0,"source_records_read":0,"source_content_stored":false,"raw_provider_payload_stored":false,"arbitrary_url_accepted":false,"arbitrary_prompt_accepted":false,"source_instructions_followed":false,"dossier_revisions_created":0,"dossier_claims_created":0,"evidence_items_created":0,"human_reviews_recorded":0,"documents_rendered":0,"exports_created":0,"contact_coordinates_created":0,"outreach_drafts_created":0,"message_send_authorized":false,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}]},"CompanyDossierTargetIn":{"properties":{"domain":{"type":"string","maxLength":253,"minLength":4,"title":"Domain","description":"The domain value for this companydossiertargetin.","examples":["Example domain"]}},"additionalProperties":false,"type":"object","required":["domain"],"title":"CompanyDossierTargetIn","description":"Name one public HTTPS host without accepting a URL, path, port, or IP literal.","examples":[{"domain":"Example domain"}]},"CompanyDossierTargetOut":{"properties":{"domain":{"type":"string","maxLength":253,"minLength":4,"title":"Domain","description":"The domain value for this companydossiertargetout.","examples":["Example domain"]},"origin":{"type":"string","minLength":1,"format":"uri","title":"Origin","description":"The origin value for this companydossiertargetout.","examples":["https://example.com"]},"root_path":{"type":"string","const":"/","title":"Root Path","description":"The root path value for this companydossiertargetout."},"arbitrary_url_accepted":{"type":"boolean","const":false,"title":"Arbitrary Url Accepted","description":"The arbitrary url accepted value for this companydossiertargetout."},"public_dns_preflight_required":{"type":"boolean","const":true,"title":"Public Dns Preflight Required","description":"The public dns preflight required value for this companydossiertargetout."}},"additionalProperties":false,"type":"object","required":["domain","origin","root_path","arbitrary_url_accepted","public_dns_preflight_required"],"title":"CompanyDossierTargetOut","description":"Structured companydossiertargetout data exposed by the public API.","examples":[{"domain":"Example domain","origin":"https://example.com","root_path":"/","arbitrary_url_accepted":false,"public_dns_preflight_required":true}]},"CompanyHeadcount":{"properties":{"min":{"anyOf":[{"type":"integer","maximum":10000000.0,"minimum":1.0},{"type":"null"}],"title":"Min","description":"The min value for this companyheadcount.","examples":[1]},"max":{"anyOf":[{"type":"integer","maximum":10000000.0,"minimum":1.0},{"type":"null"}],"title":"Max","description":"The max value for this companyheadcount.","examples":[1]}},"additionalProperties":false,"type":"object","title":"CompanyHeadcount","description":"Structured companyheadcount data exposed by the public API.","examples":[{}]},"ComplianceContext":{"properties":{"policy_basis":{"anyOf":[{"type":"string","maxLength":240},{"type":"null"}],"title":"Policy Basis","description":"The policy basis value for this compliancecontext.","examples":["Example policy basis"]},"policy_reference":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Policy Reference","description":"The policy reference value for this compliancecontext.","examples":["Example policy reference"]},"policy_version":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"title":"Policy Version","description":"The policy version value for this compliancecontext.","examples":["Example policy version"]},"jurisdiction":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}],"title":"Jurisdiction","description":"The jurisdiction value for this compliancecontext.","examples":["Example jurisdiction"]},"recipient_company_type":{"anyOf":[{"type":"string","enum":["corporation","sole_trader","partnership","public_body","unknown"]},{"type":"null"}],"title":"Recipient Company Type","description":"The recipient company type value for this compliancecontext.","examples":["corporation"]},"basis_evidence_id":{"anyOf":[{"type":"string","maxLength":240},{"type":"null"}],"title":"Basis Evidence Id","description":"The basis evidence id value for this compliancecontext.","examples":["Example basis evidence id"]},"source_provenance_id":{"anyOf":[{"type":"string","maxLength":240},{"type":"null"}],"title":"Source Provenance Id","description":"The source provenance id value for this compliancecontext.","examples":["Example source provenance id"]},"address_source":{"anyOf":[{"type":"string","enum":["first_party","provider_verified","public_business","crm","user_supplied","harvested","unknown"]},{"type":"null"}],"title":"Address Source","description":"The address source value for this compliancecontext.","examples":["first_party"]},"privacy_notice_status":{"anyOf":[{"type":"string","enum":["satisfied","not_required_by_approved_policy"]},{"type":"null"}],"title":"Privacy Notice Status","description":"The privacy notice status value for this compliancecontext.","examples":["satisfied"]}},"additionalProperties":false,"type":"object","title":"ComplianceContext","description":"Caller attestations checked against platform-owned policy and evidence state.","examples":[{}]},"ComplianceVerificationOut":{"properties":{"policy_reference":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Policy Reference","description":"Caller-attested policy reference checked against operator configuration.","examples":["POL-OUTREACH-4.2"]},"policy_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Policy Version","description":"Caller-attested policy version checked together with the reference.","examples":["2026.07"]},"policy_verified":{"type":"boolean","title":"Policy Verified","description":"Whether the exact policy reference/version pair is operator-approved.","examples":[true]},"suppression_checked_at":{"type":"string","format":"date-time","title":"Suppression Checked At","description":"Time the platform queried its scoped Outcome ledger.","examples":["2026-07-20T03:00:00Z"]},"suppressed":{"type":"boolean","title":"Suppressed","description":"Whether a scoped unsubscribe Outcome matched this prospect.","examples":[false]},"basis_evidence_verified":{"type":"boolean","title":"Basis Evidence Verified","description":"Whether the basis ID belongs to retained qualification evidence.","examples":[true]},"source_provenance_verified":{"type":"boolean","title":"Source Provenance Verified","description":"Whether address provenance belongs to retained enrichment evidence and matches its source class.","examples":[true]},"verified_address_source":{"anyOf":[{"type":"string","enum":["provider_verified","public_business","crm","user_supplied"]},{"type":"null"}],"title":"Verified Address Source","description":"Address-source class derived from the retained provenance evidence.","examples":["provider_verified"]},"verification_source":{"type":"string","const":"platform_policy_evidence_and_outcome_ledgers","title":"Verification Source","description":"Fixed marker identifying the platform-owned verification path.","default":"platform_policy_evidence_and_outcome_ledgers"}},"additionalProperties":false,"type":"object","required":["policy_verified","suppression_checked_at","suppressed","basis_evidence_verified","source_provenance_verified"],"title":"ComplianceVerificationOut","description":"Platform-derived gate facts; no value is copied from a caller decision flag.","example":{"basis_evidence_verified":true,"policy_reference":"POL-OUTREACH-4.2","policy_verified":true,"policy_version":"2026.07","source_provenance_verified":true,"suppressed":false,"suppression_checked_at":"2026-07-20T03:00:00Z","verification_source":"platform_policy_evidence_and_outcome_ledgers","verified_address_source":"provider_verified"}},"ConditionInline":{"properties":{"kind":{"type":"string","const":"condition","title":"Kind","description":"The kind value for this conditioninline."},"variable":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9]*)*$","title":"Variable","description":"The variable value for this conditioninline.","examples":["contact.firstname"]},"operator":{"$ref":"#/components/schemas/ConditionOperator","description":"The operator value for this conditioninline.","examples":["present"]},"comparison":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Comparison","description":"The comparison value for this conditioninline.","examples":["Example comparison"]},"when_true":{"items":{"oneOf":[{"$ref":"#/components/schemas/TextInline"},{"$ref":"#/components/schemas/VariableInline"}],"discriminator":{"propertyName":"kind","mapping":{"text":"#/components/schemas/TextInline","variable":"#/components/schemas/VariableInline"}}},"type":"array","maxItems":10,"title":"When True","description":"The when true value for this conditioninline.","examples":[[{"kind":"text","text":"Example text"}]]},"when_false":{"items":{"oneOf":[{"$ref":"#/components/schemas/TextInline"},{"$ref":"#/components/schemas/VariableInline"}],"discriminator":{"propertyName":"kind","mapping":{"text":"#/components/schemas/TextInline","variable":"#/components/schemas/VariableInline"}}},"type":"array","maxItems":10,"title":"When False","description":"The when false value for this conditioninline.","examples":[[{"kind":"text","text":"Example text"}]]}},"additionalProperties":false,"type":"object","required":["kind","variable","operator"],"title":"ConditionInline","description":"Structured conditioninline data exposed by the public API.","examples":[{"kind":"condition","variable":"contact.firstname","operator":"present"}]},"ConditionOperator":{"type":"string","enum":["present","equals","not_equals"],"title":"ConditionOperator","description":"Structured conditionoperator data exposed by the public API.","examples":["present"]},"ConnectionVerificationSummary":{"properties":{"mode":{"type":"string","const":"unavailable","title":"Mode","description":"The mode value for this connectionverificationsummary."},"status":{"type":"string","const":"unavailable","title":"Status","description":"The status value for this connectionverificationsummary."},"network_request_made":{"type":"boolean","const":false,"title":"Network Request Made","description":"The network request made value for this connectionverificationsummary."},"checked_at":{"type":"null","title":"Checked At","description":"The checked at value for this connectionverificationsummary.","examples":[null]}},"type":"object","required":["mode","status","network_request_made"],"title":"ConnectionVerificationSummary","description":"Structured connectionverificationsummary data exposed by the public API.","examples":[{"mode":"unavailable","status":"unavailable","network_request_made":false}]},"ConnectorCatalogResponse":{"properties":{"catalog_version":{"type":"string","title":"Catalog Version","description":"The catalog version value for this connectorcatalogresponse.","examples":["Example catalog version"]},"connectors":{"items":{"$ref":"#/components/schemas/ConnectorManifestOut"},"type":"array","title":"Connectors","description":"The connectors value for this connectorcatalogresponse.","examples":[[{"manifest_version":"Example manifest version","key":"Example key","name":"Example name","category":"Example category","declared_integration_kinds":["rest"],"availability":"catalog_only","verification_mode":"unavailable","homepage_url":"https://example.com","docs_url":"https://example.com","key_acquisition_url":"https://example.com","capabilities":["Example capabilities"],"credential_fields":[{"key":"Example key","label":"Example label","description":"Example description","environment_aliases":["Example environment aliases"],"required":true,"secret":true}],"provenance":{"repository":"Example repository","commit":"Example commit","source_paths":["Example source paths"]}}]]}},"type":"object","required":["catalog_version","connectors"],"title":"ConnectorCatalogResponse","description":"Structured connectorcatalogresponse data exposed by the public API.","examples":[{"catalog_version":"Example catalog version","connectors":[{"manifest_version":"Example manifest version","key":"Example key","name":"Example name","category":"Example category","declared_integration_kinds":["rest"],"availability":"catalog_only","verification_mode":"unavailable","homepage_url":"https://example.com","docs_url":"https://example.com","key_acquisition_url":"https://example.com","capabilities":["Example capabilities"],"credential_fields":[{"key":"Example key","label":"Example label","description":"Example description","environment_aliases":["Example environment aliases"],"required":true,"secret":true}],"provenance":{"repository":"Example repository","commit":"Example commit","source_paths":["Example source paths"]}}]}]},"ConnectorManifestOut":{"properties":{"manifest_version":{"type":"string","title":"Manifest Version","description":"The manifest version value for this connectormanifestout.","examples":["Example manifest version"]},"key":{"type":"string","title":"Key","description":"The key value for this connectormanifestout.","examples":["Example key"]},"name":{"type":"string","title":"Name","description":"The name value for this connectormanifestout.","examples":["Example name"]},"category":{"type":"string","title":"Category","description":"The category value for this connectormanifestout.","examples":["Example category"]},"declared_integration_kinds":{"items":{"type":"string","enum":["rest","mcp","smtp","oauth2","webhook"]},"type":"array","title":"Declared Integration Kinds","description":"The declared integration kinds value for this connectormanifestout.","examples":[["rest"]]},"availability":{"type":"string","const":"catalog_only","title":"Availability","description":"The availability value for this connectormanifestout."},"verification_mode":{"type":"string","const":"unavailable","title":"Verification Mode","description":"The verification mode value for this connectormanifestout."},"homepage_url":{"type":"string","title":"Homepage Url","description":"The homepage url value for this connectormanifestout.","examples":["https://example.com"]},"docs_url":{"type":"string","title":"Docs Url","description":"The docs url value for this connectormanifestout.","examples":["https://example.com"]},"key_acquisition_url":{"type":"string","title":"Key Acquisition Url","description":"The key acquisition url value for this connectormanifestout.","examples":["https://example.com"]},"capabilities":{"items":{"type":"string"},"type":"array","title":"Capabilities","description":"The capabilities value for this connectormanifestout.","examples":[["Example capabilities"]]},"credential_fields":{"items":{"$ref":"#/components/schemas/CredentialFieldOut"},"type":"array","title":"Credential Fields","description":"The credential fields value for this connectormanifestout.","examples":[[{"key":"Example key","label":"Example label","description":"Example description","environment_aliases":["Example environment aliases"],"required":true,"secret":true}]]},"provenance":{"$ref":"#/components/schemas/ConnectorProvenanceOut","description":"The provenance value for this connectormanifestout.","examples":[{"repository":"Example repository","commit":"Example commit","source_paths":["Example source paths"]}]}},"type":"object","required":["manifest_version","key","name","category","declared_integration_kinds","availability","verification_mode","homepage_url","docs_url","key_acquisition_url","capabilities","credential_fields","provenance"],"title":"ConnectorManifestOut","description":"Structured connectormanifestout data exposed by the public API.","examples":[{"manifest_version":"Example manifest version","key":"Example key","name":"Example name","category":"Example category","declared_integration_kinds":["rest"],"availability":"catalog_only","verification_mode":"unavailable","homepage_url":"https://example.com","docs_url":"https://example.com","key_acquisition_url":"https://example.com","capabilities":["Example capabilities"],"credential_fields":[{"key":"Example key","label":"Example label","description":"Example description","environment_aliases":["Example environment aliases"],"required":true,"secret":true}],"provenance":{"repository":"Example repository","commit":"Example commit","source_paths":["Example source paths"]}}]},"ConnectorProvenanceOut":{"properties":{"repository":{"type":"string","title":"Repository","description":"The repository value for this connectorprovenanceout.","examples":["Example repository"]},"commit":{"type":"string","title":"Commit","description":"The commit value for this connectorprovenanceout.","examples":["Example commit"]},"source_paths":{"items":{"type":"string"},"type":"array","title":"Source Paths","description":"The source paths value for this connectorprovenanceout.","examples":[["Example source paths"]]}},"type":"object","required":["repository","commit","source_paths"],"title":"ConnectorProvenanceOut","description":"Structured connectorprovenanceout data exposed by the public API.","examples":[{"repository":"Example repository","commit":"Example commit","source_paths":["Example source paths"]}]},"CountryCode":{"type":"string","enum":["AD","AE","AF","AG","AI","AL","AM","AO","AQ","AR","AS","AT","AU","AW","AX","AZ","BA","BB","BD","BE","BF","BG","BH","BI","BJ","BL","BM","BN","BO","BQ","BR","BS","BT","BV","BW","BY","BZ","CA","CC","CD","CF","CG","CH","CI","CK","CL","CM","CN","CO","CR","CU","CV","CW","CX","CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","EH","ER","ES","ET","FI","FJ","FK","FM","FO","FR","GA","GB","GD","GE","GF","GG","GH","GI","GL","GM","GN","GP","GQ","GR","GS","GT","GU","GW","GY","HK","HM","HN","HR","HT","HU","ID","IE","IL","IM","IN","IO","IQ","IR","IS","IT","JE","JM","JO","JP","KE","KG","KH","KI","KM","KN","KP","KR","KW","KY","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MC","MD","ME","MF","MG","MH","MK","ML","MM","MN","MO","MP","MQ","MR","MS","MT","MU","MV","MW","MX","MY","MZ","NA","NC","NE","NF","NG","NI","NL","NO","NP","NR","NU","NZ","OM","PA","PE","PF","PG","PH","PK","PL","PM","PN","PR","PS","PT","PW","PY","QA","RE","RO","RS","RU","RW","SA","SB","SC","SD","SE","SG","SH","SI","SJ","SK","SL","SM","SN","SO","SR","SS","ST","SV","SX","SY","SZ","TC","TD","TF","TG","TH","TJ","TK","TL","TM","TN","TO","TR","TT","TV","TW","TZ","UA","UG","UM","US","UY","UZ","VA","VC","VE","VG","VI","VN","VU","WF","WS","YE","YT","ZA","ZM","ZW"],"title":"CountryCode","description":"Structured countrycode data exposed by the public API.","examples":["AD"]},"CrawlerIdentity":{"properties":{"check":{"$ref":"#/components/schemas/SiteAuditCheckId","description":"The check value for this crawleridentity.","examples":["title_tag"]},"provider":{"type":"string","enum":["OpenAI","Anthropic","Perplexity"],"title":"Provider","description":"The provider value for this crawleridentity.","examples":["OpenAI"]},"product":{"type":"string","maxLength":80,"minLength":1,"title":"Product","description":"The product value for this crawleridentity.","examples":["Example product"]},"user_agent":{"type":"string","enum":["OAI-SearchBot","Claude-SearchBot","Claude-User","PerplexityBot"],"title":"User Agent","description":"The user agent value for this crawleridentity.","examples":["OAI-SearchBot"]},"purpose":{"type":"string","enum":["search_index","user_directed_fetch"],"title":"Purpose","description":"The purpose value for this crawleridentity.","examples":["search_index"]},"official_documentation_url":{"type":"string","minLength":1,"format":"uri","title":"Official Documentation Url","description":"The official documentation url value for this crawleridentity.","examples":["https://example.com"]},"robots_txt_evaluation_only":{"type":"boolean","const":true,"title":"Robots Txt Evaluation Only","description":"The robots txt evaluation only value for this crawleridentity."},"impersonation_authorized":{"type":"boolean","const":false,"title":"Impersonation Authorized","description":"The impersonation authorized value for this crawleridentity."}},"additionalProperties":false,"type":"object","required":["check","provider","product","user_agent","purpose","official_documentation_url","robots_txt_evaluation_only","impersonation_authorized"],"title":"CrawlerIdentity","description":"Structured crawleridentity data exposed by the public API.","examples":[{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false}]},"CrawlerRegistry":{"properties":{"version":{"type":"string","const":"2026-07-13","title":"Version","description":"The version value for this crawlerregistry."},"revalidation_required_before_execution":{"type":"boolean","const":true,"title":"Revalidation Required Before Execution","description":"The revalidation required before execution value for this crawlerregistry."},"robots_standard":{"type":"string","const":"RFC 9309","title":"Robots Standard","description":"The robots standard value for this crawlerregistry."},"official_standard_url":{"type":"string","minLength":1,"format":"uri","title":"Official Standard Url","description":"The official standard url value for this crawlerregistry.","examples":["https://example.com"]},"longest_match_required":{"type":"boolean","const":true,"title":"Longest Match Required","description":"The longest match required value for this crawlerregistry."},"matching_groups_must_be_merged":{"type":"boolean","const":true,"title":"Matching Groups Must Be Merged","description":"The matching groups must be merged value for this crawlerregistry."},"robots_rules_are_authorization":{"type":"boolean","const":false,"title":"Robots Rules Are Authorization","description":"The robots rules are authorization value for this crawlerregistry."},"identities":{"items":{"$ref":"#/components/schemas/CrawlerIdentity"},"type":"array","maxItems":4,"minItems":4,"title":"Identities","description":"The identities value for this crawlerregistry.","examples":[[{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false}]]}},"additionalProperties":false,"type":"object","required":["version","revalidation_required_before_execution","robots_standard","official_standard_url","longest_match_required","matching_groups_must_be_merged","robots_rules_are_authorization","identities"],"title":"CrawlerRegistry","description":"Structured crawlerregistry data exposed by the public API.","examples":[{"version":"2026-07-13","revalidation_required_before_execution":true,"robots_standard":"RFC 9309","official_standard_url":"https://example.com","longest_match_required":true,"matching_groups_must_be_merged":true,"robots_rules_are_authorization":false,"identities":[{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false}]}]},"CredentialFieldOut":{"properties":{"key":{"type":"string","title":"Key","description":"The key value for this credentialfieldout.","examples":["Example key"]},"label":{"type":"string","title":"Label","description":"The label value for this credentialfieldout.","examples":["Example label"]},"description":{"type":"string","title":"Description","description":"The description value for this credentialfieldout.","examples":["Example description"]},"environment_aliases":{"items":{"type":"string"},"type":"array","title":"Environment Aliases","description":"The environment aliases value for this credentialfieldout.","examples":[["Example environment aliases"]]},"required":{"type":"boolean","title":"Required","description":"The required value for this credentialfieldout.","examples":[true]},"secret":{"type":"boolean","title":"Secret","description":"The secret value for this credentialfieldout.","examples":[true]}},"type":"object","required":["key","label","description","environment_aliases","required","secret"],"title":"CredentialFieldOut","description":"Structured credentialfieldout data exposed by the public API.","examples":[{"key":"Example key","label":"Example label","description":"Example description","environment_aliases":["Example environment aliases"],"required":true,"secret":true}]},"CredentialRequirement":{"type":"string","enum":["none","sam_gov_public_api_key"],"title":"CredentialRequirement","description":"Structured credentialrequirement data exposed by the public API.","examples":["none"]},"DataClassification":{"type":"string","enum":["public_organization","public_business_contact","public_location","public_registry"],"title":"DataClassification","description":"Structured dataclassification data exposed by the public API.","examples":["public_organization"]},"DataIntakeDeduplicationIn":{"properties":{"match_keys":{"items":{"$ref":"#/components/schemas/DeduplicationKey"},"type":"array","maxItems":4,"minItems":1,"title":"Match Keys","description":"The match keys value for this dataintakededuplicationin.","examples":[["source_record_id"]]},"on_match":{"type":"string","const":"skip","title":"On Match","default":"skip","description":"The on match value for this dataintakededuplicationin."}},"additionalProperties":false,"type":"object","required":["match_keys"],"title":"DataIntakeDeduplicationIn","description":"Structured dataintakededuplicationin data exposed by the public API.","examples":[{"match_keys":["source_record_id"]}]},"DataIntakeFieldSpecification":{"properties":{"field":{"$ref":"#/components/schemas/IntakeField","description":"The field value for this dataintakefieldspecification.","examples":["source_record_id"]},"value_type":{"$ref":"#/components/schemas/IntakeValueType","description":"The value type value for this dataintakefieldspecification.","examples":["identifier"]},"data_classification":{"$ref":"#/components/schemas/DataClassification","description":"The data classification value for this dataintakefieldspecification.","examples":["public_organization"]},"evidence_required":{"type":"boolean","const":true,"title":"Evidence Required","description":"The evidence required value for this dataintakefieldspecification."}},"additionalProperties":false,"type":"object","required":["field","value_type","data_classification","evidence_required"],"title":"DataIntakeFieldSpecification","description":"Structured dataintakefieldspecification data exposed by the public API.","examples":[{"field":"source_record_id","value_type":"identifier","data_classification":"public_organization","evidence_required":true}]},"DataIntakePolicyVersion":{"type":"string","enum":["2026-07-13"],"title":"DataIntakePolicyVersion","description":"Readable/replayable policies; append versions, never replace them.","examples":["2026-07-13"]},"DataIntakeSchemaVersion":{"type":"string","enum":["2026-07-13"],"title":"DataIntakeSchemaVersion","description":"Readable historical response schemas; append versions, never replace them.","examples":["2026-07-13"]},"DataIntakeSelectionIn":{"properties":{"country_code":{"type":"string","const":"US","title":"Country Code","default":"US","description":"The country code value for this dataintakeselectionin."},"region_codes":{"items":{"type":"string","pattern":"^[A-Z]{2}$"},"type":"array","maxItems":20,"title":"Region Codes","description":"The region codes value for this dataintakeselectionin.","examples":[["NZ"]]},"postal_codes":{"items":{"type":"string","pattern":"^\\d{5}$"},"type":"array","maxItems":100,"title":"Postal Codes","description":"The postal codes value for this dataintakeselectionin.","examples":[["10101"]]},"category_codes":{"items":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z0-9]+(?:[._:-][a-z0-9]+)*$"},"type":"array","maxItems":50,"title":"Category Codes","description":"The category codes value for this dataintakeselectionin.","examples":[["example.code"]]},"radius_miles":{"anyOf":[{"type":"integer","maximum":50.0,"minimum":1.0},{"type":"null"}],"title":"Radius Miles","description":"The radius miles value for this dataintakeselectionin.","examples":[1]},"max_records":{"type":"integer","maximum":100000.0,"minimum":1.0,"title":"Max Records","description":"The max records value for this dataintakeselectionin.","examples":[1]}},"additionalProperties":false,"type":"object","required":["max_records"],"title":"DataIntakeSelectionIn","description":"Bound one US-only source selection without arbitrary provider query text.","examples":[{"max_records":1}]},"DataIntakeSourceIn":{"properties":{"source":{"$ref":"#/components/schemas/DataSource","description":"The source value for this dataintakesourcein.","examples":["overture_places"]},"version":{"type":"string","maxLength":32,"minLength":2,"pattern":"^(?:\\d{4}-\\d{2}-\\d{2}\\.\\d+|2\\.1|v3|v4|(?:daily|weekly):\\d{4}-\\d{2}-\\d{2})$","title":"Version","description":"The version value for this dataintakesourcein.","examples":["2026-07-15.1"]},"snapshot_manifest_sha256":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{64}$"},{"type":"null"}],"title":"Snapshot Manifest Sha256","description":"The snapshot manifest sha256 value for this dataintakesourcein.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]}},"additionalProperties":false,"type":"object","required":["source","version"],"title":"DataIntakeSourceIn","description":"Name an allow-listed source and exact version without accepting a URL or credential.","examples":[{"source":"overture_places","version":"2026-07-15.1"}]},"DataIntakeSourcePolicy":{"properties":{"source":{"$ref":"#/components/schemas/DataSource","description":"The source value for this dataintakesourcepolicy.","examples":["overture_places"]},"display_name":{"type":"string","maxLength":120,"minLength":1,"title":"Display Name","description":"The display name value for this dataintakesourcepolicy.","examples":["Example display name"]},"access_mode":{"$ref":"#/components/schemas/SourceAccessMode","description":"The access mode value for this dataintakesourcepolicy.","examples":["anonymous_public_snapshot"]},"credential_requirement":{"$ref":"#/components/schemas/CredentialRequirement","description":"The credential requirement value for this dataintakesourcepolicy.","examples":["none"]},"credential_acquisition_url":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Credential Acquisition Url","description":"The credential acquisition url value for this dataintakesourcepolicy.","examples":["https://example.com"]},"official_documentation_url":{"type":"string","maxLength":500,"minLength":1,"title":"Official Documentation Url","description":"The official documentation url value for this dataintakesourcepolicy.","examples":["https://example.com"]},"required_connector_capability":{"$ref":"#/components/schemas/app__data_intake_schema__RequiredConnectorCapability","description":"The required connector capability value for this dataintakesourcepolicy.","examples":["public-dataset-read"]},"snapshot_manifest_required":{"type":"boolean","title":"Snapshot Manifest Required","description":"The snapshot manifest required value for this dataintakesourcepolicy.","examples":[true]},"version_availability_revalidation_required":{"type":"boolean","const":true,"title":"Version Availability Revalidation Required","description":"The version availability revalidation required value for this dataintakesourcepolicy."},"terms_review_required":{"type":"boolean","const":true,"title":"Terms Review Required","description":"The terms review required value for this dataintakesourcepolicy."},"attribution_required":{"type":"boolean","title":"Attribution Required","description":"The attribution required value for this dataintakesourcepolicy.","examples":[true]},"maximum_records":{"type":"integer","maximum":100000.0,"minimum":1.0,"title":"Maximum Records","description":"The maximum records value for this dataintakesourcepolicy.","examples":[1]}},"additionalProperties":false,"type":"object","required":["source","display_name","access_mode","credential_requirement","official_documentation_url","required_connector_capability","snapshot_manifest_required","version_availability_revalidation_required","terms_review_required","attribution_required","maximum_records"],"title":"DataIntakeSourcePolicy","description":"Structured dataintakesourcepolicy data exposed by the public API.","examples":[{"source":"overture_places","display_name":"Example display name","access_mode":"anonymous_public_snapshot","credential_requirement":"none","official_documentation_url":"https://example.com","required_connector_capability":"public-dataset-read","snapshot_manifest_required":true,"version_availability_revalidation_required":true,"terms_review_required":true,"attribution_required":true,"maximum_records":1}]},"DataIntakeSpecificationCreateIn":{"properties":{"key":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","title":"Key","description":"The key value for this dataintakespecificationcreatein.","examples":["example-key"]},"source":{"$ref":"#/components/schemas/DataIntakeSourceIn","description":"The source value for this dataintakespecificationcreatein.","examples":[{"source":"overture_places","version":"2026-07-15.1"}]},"selection":{"$ref":"#/components/schemas/DataIntakeSelectionIn","description":"The selection value for this dataintakespecificationcreatein.","examples":[{"max_records":1}]},"fields":{"items":{"$ref":"#/components/schemas/IntakeField"},"type":"array","maxItems":16,"minItems":2,"title":"Fields","description":"The fields value for this dataintakespecificationcreatein.","examples":[["source_record_id","source_record_id"]]},"deduplication":{"$ref":"#/components/schemas/DataIntakeDeduplicationIn","description":"The deduplication value for this dataintakespecificationcreatein.","examples":[{"match_keys":["source_record_id"]}]},"purpose":{"$ref":"#/components/schemas/IntakePurpose","description":"The purpose value for this dataintakespecificationcreatein.","examples":["account_discovery"]},"retention_days":{"type":"integer","maximum":365.0,"minimum":1.0,"title":"Retention Days","description":"The retention days value for this dataintakespecificationcreatein.","examples":[1]},"expected_policy_version":{"$ref":"#/components/schemas/DataIntakePolicyVersion","description":"The expected policy version value for this dataintakespecificationcreatein.","examples":["2026-07-13"]},"reason":{"type":"string","maxLength":500,"minLength":3,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"Reason","description":"The reason value for this dataintakespecificationcreatein.","examples":["Example value"]}},"additionalProperties":false,"type":"object","required":["key","source","selection","fields","deduplication","purpose","retention_days","expected_policy_version","reason"],"title":"DataIntakeSpecificationCreateIn","description":"Freeze an exact source intake plan; inputs cannot carry rows, URLs, queries, or secrets.","examples":[{"key":"example-key","source":{"source":"overture_places","version":"2026-07-15.1"},"selection":{"max_records":1},"fields":["source_record_id","source_record_id"],"deduplication":{"match_keys":["source_record_id"]},"purpose":"account_discovery","retention_days":1,"expected_policy_version":"2026-07-13","reason":"Example value"}]},"DataIntakeSpecificationListOut":{"properties":{"specifications":{"items":{"$ref":"#/components/schemas/DataIntakeSpecificationOut"},"type":"array","title":"Specifications","description":"The specifications value for this dataintakespecificationlistout.","examples":[[{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"intakespec_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","source":{"source":"overture_places","version":"2026-07-15.1"},"source_policy":{"source":"overture_places","display_name":"Example display name","access_mode":"anonymous_public_snapshot","credential_requirement":"none","official_documentation_url":"https://example.com","required_connector_capability":"public-dataset-read","snapshot_manifest_required":true,"version_availability_revalidation_required":true,"terms_review_required":true,"attribution_required":true,"maximum_records":1},"selection":{"max_records":1},"field_specs":[{"field":"source_record_id","value_type":"identifier","data_classification":"public_organization","evidence_required":true},{"field":"source_record_id","value_type":"identifier","data_classification":"public_organization","evidence_required":true}],"deduplication":{"match_keys":["source_record_id"]},"purpose":"account_discovery","retention_days":1,"policy_version":"2026-07-13","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"source_requests_made":0,"bytes_received":0,"records_read":0,"records_staged":0,"records_written":0,"matches_attempted":0,"upload_authorized":false,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}]]},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"The total value for this dataintakespecificationlistout.","examples":[0]},"limit":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Limit","description":"The limit value for this dataintakespecificationlistout.","examples":[1]},"offset":{"type":"integer","maximum":10000.0,"minimum":0.0,"title":"Offset","description":"The offset value for this dataintakespecificationlistout.","examples":[0]},"availability":{"type":"string","const":"contract_only","title":"Availability","description":"The availability value for this dataintakespecificationlistout."},"execution_available":{"type":"boolean","const":false,"title":"Execution Available","description":"The execution available value for this dataintakespecificationlistout."},"source_requests_made":{"type":"integer","const":0,"title":"Source Requests Made","description":"The source requests made value for this dataintakespecificationlistout."}},"additionalProperties":false,"type":"object","required":["specifications","total","limit","offset","availability","execution_available","source_requests_made"],"title":"DataIntakeSpecificationListOut","description":"Structured dataintakespecificationlistout data exposed by the public API.","examples":[{"specifications":[{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"intakespec_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","source":{"source":"overture_places","version":"2026-07-15.1"},"source_policy":{"source":"overture_places","display_name":"Example display name","access_mode":"anonymous_public_snapshot","credential_requirement":"none","official_documentation_url":"https://example.com","required_connector_capability":"public-dataset-read","snapshot_manifest_required":true,"version_availability_revalidation_required":true,"terms_review_required":true,"attribution_required":true,"maximum_records":1},"selection":{"max_records":1},"field_specs":[{"field":"source_record_id","value_type":"identifier","data_classification":"public_organization","evidence_required":true},{"field":"source_record_id","value_type":"identifier","data_classification":"public_organization","evidence_required":true}],"deduplication":{"match_keys":["source_record_id"]},"purpose":"account_discovery","retention_days":1,"policy_version":"2026-07-13","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"source_requests_made":0,"bytes_received":0,"records_read":0,"records_staged":0,"records_written":0,"matches_attempted":0,"upload_authorized":false,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}],"total":0,"limit":1,"offset":0,"availability":"contract_only","execution_available":false,"source_requests_made":0}]},"DataIntakeSpecificationOut":{"properties":{"schema_version":{"$ref":"#/components/schemas/DataIntakeSchemaVersion","description":"The schema version value for this dataintakespecificationout.","examples":["2026-07-13"]},"status":{"type":"string","const":"specified","title":"Status","description":"The status value for this dataintakespecificationout."},"availability":{"type":"string","const":"contract_only","title":"Availability","description":"The availability value for this dataintakespecificationout."},"id":{"type":"string","pattern":"^intakespec_[a-f0-9]{24}$","title":"Id","description":"The id value for this dataintakespecificationout.","examples":["intakespec_aaaaaaaaaaaaaaaaaaaaaaaa"]},"idempotent_replay":{"type":"boolean","title":"Idempotent Replay","description":"The idempotent replay value for this dataintakespecificationout.","examples":[true]},"key":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","title":"Key","description":"The key value for this dataintakespecificationout.","examples":["example-key"]},"project_id":{"type":"string","pattern":"^proj_[a-f0-9]{24}$","title":"Project Id","description":"The project id value for this dataintakespecificationout.","examples":["proj_aaaaaaaaaaaaaaaaaaaaaaaa"]},"environment":{"type":"string","enum":["live","test"],"title":"Environment","description":"The environment value for this dataintakespecificationout.","examples":["live"]},"source":{"$ref":"#/components/schemas/DataIntakeSourceIn","description":"The source value for this dataintakespecificationout.","examples":[{"source":"overture_places","version":"2026-07-15.1"}]},"source_policy":{"$ref":"#/components/schemas/DataIntakeSourcePolicy","description":"The source policy value for this dataintakespecificationout.","examples":[{"source":"overture_places","display_name":"Example display name","access_mode":"anonymous_public_snapshot","credential_requirement":"none","official_documentation_url":"https://example.com","required_connector_capability":"public-dataset-read","snapshot_manifest_required":true,"version_availability_revalidation_required":true,"terms_review_required":true,"attribution_required":true,"maximum_records":1}]},"selection":{"$ref":"#/components/schemas/DataIntakeSelectionIn","description":"The selection value for this dataintakespecificationout.","examples":[{"max_records":1}]},"field_specs":{"items":{"$ref":"#/components/schemas/DataIntakeFieldSpecification"},"type":"array","maxItems":16,"minItems":2,"title":"Field Specs","description":"The field specs value for this dataintakespecificationout.","examples":[[{"field":"source_record_id","value_type":"identifier","data_classification":"public_organization","evidence_required":true},{"field":"source_record_id","value_type":"identifier","data_classification":"public_organization","evidence_required":true}]]},"deduplication":{"$ref":"#/components/schemas/DataIntakeDeduplicationIn","description":"The deduplication value for this dataintakespecificationout.","examples":[{"match_keys":["source_record_id"]}]},"purpose":{"$ref":"#/components/schemas/IntakePurpose","description":"The purpose value for this dataintakespecificationout.","examples":["account_discovery"]},"retention_days":{"type":"integer","maximum":365.0,"minimum":1.0,"title":"Retention Days","description":"The retention days value for this dataintakespecificationout.","examples":[1]},"policy_version":{"$ref":"#/components/schemas/DataIntakePolicyVersion","description":"The policy version value for this dataintakespecificationout.","examples":["2026-07-13"]},"specification_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Specification Hash","description":"The specification hash value for this dataintakespecificationout.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"reason":{"type":"string","maxLength":500,"minLength":3,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"Reason","description":"The reason value for this dataintakespecificationout.","examples":["Example value"]},"execution_available":{"type":"boolean","const":false,"title":"Execution Available","description":"The execution available value for this dataintakespecificationout."},"execution_authorized":{"type":"boolean","const":false,"title":"Execution Authorized","description":"The execution authorized value for this dataintakespecificationout."},"source_requests_made":{"type":"integer","const":0,"title":"Source Requests Made","description":"The source requests made value for this dataintakespecificationout."},"bytes_received":{"type":"integer","const":0,"title":"Bytes Received","description":"The bytes received value for this dataintakespecificationout."},"records_read":{"type":"integer","const":0,"title":"Records Read","description":"The records read value for this dataintakespecificationout."},"records_staged":{"type":"integer","const":0,"title":"Records Staged","description":"The records staged value for this dataintakespecificationout."},"records_written":{"type":"integer","const":0,"title":"Records Written","description":"The records written value for this dataintakespecificationout."},"matches_attempted":{"type":"integer","const":0,"title":"Matches Attempted","description":"The matches attempted value for this dataintakespecificationout."},"upload_authorized":{"type":"boolean","const":false,"title":"Upload Authorized","description":"The upload authorized value for this dataintakespecificationout."},"export_authorized":{"type":"boolean","const":false,"title":"Export Authorized","description":"The export authorized value for this dataintakespecificationout."},"outbound_authorized":{"type":"boolean","const":false,"title":"Outbound Authorized","description":"The outbound authorized value for this dataintakespecificationout."},"crm_mutation_authorized":{"type":"boolean","const":false,"title":"Crm Mutation Authorized","description":"The crm mutation authorized value for this dataintakespecificationout."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"The created at value for this dataintakespecificationout.","examples":["2026-07-16T00:00:00Z"]}},"additionalProperties":false,"type":"object","required":["schema_version","status","availability","id","idempotent_replay","key","project_id","environment","source","source_policy","selection","field_specs","deduplication","purpose","retention_days","policy_version","specification_hash","reason","execution_available","execution_authorized","source_requests_made","bytes_received","records_read","records_staged","records_written","matches_attempted","upload_authorized","export_authorized","outbound_authorized","crm_mutation_authorized","created_at"],"title":"DataIntakeSpecificationOut","description":"Persisted contract-only plan. Every I/O, processing, and effect claim remains zero/false.","examples":[{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"intakespec_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","source":{"source":"overture_places","version":"2026-07-15.1"},"source_policy":{"source":"overture_places","display_name":"Example display name","access_mode":"anonymous_public_snapshot","credential_requirement":"none","official_documentation_url":"https://example.com","required_connector_capability":"public-dataset-read","snapshot_manifest_required":true,"version_availability_revalidation_required":true,"terms_review_required":true,"attribution_required":true,"maximum_records":1},"selection":{"max_records":1},"field_specs":[{"field":"source_record_id","value_type":"identifier","data_classification":"public_organization","evidence_required":true},{"field":"source_record_id","value_type":"identifier","data_classification":"public_organization","evidence_required":true}],"deduplication":{"match_keys":["source_record_id"]},"purpose":"account_discovery","retention_days":1,"policy_version":"2026-07-13","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"source_requests_made":0,"bytes_received":0,"records_read":0,"records_staged":0,"records_written":0,"matches_attempted":0,"upload_authorized":false,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}]},"DataSource":{"type":"string","enum":["overture_places","nppes_npi_registry","sam_gov_entities","fcc_uls"],"title":"DataSource","description":"Structured datasource data exposed by the public API.","examples":["overture_places"]},"DeduplicationKey":{"type":"string","enum":["source_record_id","provider_identifier","normalized_domain","normalized_phone","organization_name_region_postal"],"title":"DeduplicationKey","description":"Structured deduplicationkey data exposed by the public API.","examples":["source_record_id"]},"Differentiator":{"properties":{"name":{"type":"string","maxLength":160,"title":"Name","description":"The name value for this differentiator.","examples":["Example name"]},"description":{"type":"string","maxLength":1000,"title":"Description","description":"The description value for this differentiator.","examples":["Example description"]},"proof_points":{"items":{"type":"string"},"type":"array","maxItems":12,"title":"Proof Points","description":"The proof points value for this differentiator.","examples":[["Example proof points"]]}},"additionalProperties":false,"type":"object","required":["name","description"],"title":"Differentiator","description":"Structured differentiator data exposed by the public API.","examples":[{"name":"Example name","description":"Example description"}]},"DocumentBrandRef":{"properties":{"profile_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Profile Id","description":"Brand profile identifier.","examples":["brand_01h8z3m2q7"]},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Brand display name.","examples":["Northstar Analytics"]},"key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key","description":"Stable brand profile key.","examples":["northstar"]}},"type":"object","title":"DocumentBrandRef","description":"The platform brand whose Brand Pack branded this document.","examples":[{"key":"northstar","name":"Northstar Analytics","profile_id":"brand_01h8z3m2q7"}]},"DocumentFileRef":{"properties":{"file_id":{"type":"string","title":"File Id","description":"Stable identifier of the stored file within the job.","examples":["docfile_01h8z3m2q7"]},"filename":{"type":"string","title":"Filename","description":"Filename the agent saved the document as.","examples":["acme-corporation-proposal.docx"]},"format":{"type":"string","enum":["pptx","docx","pdf","other"],"title":"Format","description":"File format derived from the filename extension.","examples":["docx"]},"size_bytes":{"type":"integer","minimum":0.0,"title":"Size Bytes","description":"Stored file size in bytes.","examples":[48213]},"download_path":{"type":"string","title":"Download Path","description":"Console-relative download path for the file bytes (informational). API callers download via `GET /v1/documents/{job_id}/files/{file_id}`.","examples":["/api/orgs/org_123/projects/proj_123/documents/job_document_123/files/docfile_01h8z3m2q7"]}},"type":"object","required":["file_id","filename","format","size_bytes","download_path"],"title":"DocumentFileRef","description":"One stored collateral file produced by the run.","examples":[{"download_path":"/api/orgs/org_123/projects/proj_123/documents/job_document_123/files/docfile_01h8z3m2q7","file_id":"docfile_01h8z3m2q7","filename":"acme-corporation-proposal.docx","format":"docx","size_bytes":48213}]},"DocumentInput":{"properties":{"brief":{"type":"string","maxLength":8000,"minLength":1,"title":"Brief","description":"What to create: the document ask, its audience, and the key points to cover. This is the core instruction the generation agent works from.","examples":["A first-meeting sales proposal for Acme Corporation's RevOps team: lead with their pipeline-visibility pains, map our onboarding time-to-value, and close with a 90-day rollout plan and pricing summary."]},"document_type":{"anyOf":[{"type":"string","enum":["proposal","playbook","deck","gtm_strategy","report","one_pager"]},{"type":"null"}],"title":"Document Type","description":"Kind of collateral to produce. Null lets the agent decide the best type from the brief.","examples":["proposal"]},"format":{"anyOf":[{"type":"string","enum":["pptx","docx","pdf"]},{"type":"null"}],"title":"Format","description":"Output file format. Null lets the agent pick the format that best fits the document type.","examples":["docx"]},"target_domain":{"anyOf":[{"type":"string","maxLength":253},{"type":"null"}],"title":"Target Domain","description":"Optional company domain the agent researches as the document's focus account. Bare domains resolve best (`acme.example`); schemes, `www.` and paths are stripped automatically. Null for collateral without a single target account.","examples":["acme.example"]},"brand":{"anyOf":[{"type":"string","maxLength":120,"minLength":1},{"type":"null"}],"title":"Brand","description":"Brand profile ID (`brand_…`) or key whose Brand Pack brands the document; null uses the organization's default brand. The brand must have a completed guideline (run brand research first).","examples":["northstar"]},"offer":{"anyOf":[{"type":"string","maxLength":120,"minLength":1},{"type":"null"}],"title":"Offer","description":"Offer ID (`offer_…`) or key whose selling substance (value props, proof points, pricing, ICP, stage fit) is attached to the run; null attaches no offer.","examples":["analytics_suite"]},"template_urls":{"items":{"type":"string"},"type":"array","maxItems":3,"title":"Template Urls","description":"Up to three http(s) URLs of reference or template documents. The agent fetches them and follows their structure, tone and layout conventions.","examples":[["https://cdn.example/templates/enterprise-proposal.docx"]]},"title":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}],"title":"Title","description":"Caller-supplied document title retained with the job and echoed in the result; null when omitted.","examples":["Acme Corporation proposal"]},"external_ref":{"anyOf":[{"type":"string","maxLength":240},{"type":"null"}],"title":"External Ref","description":"Caller-supplied correlation reference echoed in the result; null when omitted.","examples":["crm-account-123"]}},"additionalProperties":false,"type":"object","required":["brief"],"title":"DocumentInput","description":"Create one sales-collateral file run (proposal, playbook, deck, report...).","examples":[{"brand":"northstar","brief":"A first-meeting sales proposal for Acme Corporation's RevOps team: lead with their pipeline-visibility pains, map our onboarding time-to-value, and close with a 90-day rollout plan and pricing summary.","document_type":"proposal","external_ref":"crm-account-123","format":"docx","offer":"analytics_suite","target_domain":"acme.example","template_urls":["https://cdn.example/templates/enterprise-proposal.docx"],"title":"Acme Corporation proposal"}]},"DocumentJobResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Stable asynchronous job identifier.","examples":["job_playbook_123"]},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"],"title":"Status","description":"Current job state.","examples":["succeeded"]},"progress":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Progress","description":"Coarse completion percentage. Terminal successful jobs report 100.","examples":[100]},"project_id":{"type":"string","title":"Project Id","description":"Project that owns the job and its usage.","examples":["proj_123"]},"campaign_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Campaign Id","description":"Owning Audience campaign; null for Playbooks jobs.","examples":["camp_123"]},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Stable human-readable job failure message; null unless the job failed.","examples":[null]},"error_code":{"anyOf":[{"$ref":"#/components/schemas/PublicErrorCode"},{"type":"null"}],"description":"Stable machine-readable public failure code when one applies; null otherwise.","examples":["insufficient_credits"]},"usage":{"$ref":"#/components/schemas/PublicJobUsage","description":"Usage attributed to this job.","examples":[{"backend_requests":1,"backend_runtime_ms":1830,"cache_write_tokens":300,"cached_input_tokens":1200,"cost_usd":0.0123,"input_tokens":3500,"output_tokens":700,"reasoning_tokens":180,"tokens":4200}]},"stages":{"anyOf":[{"items":{"$ref":"#/components/schemas/PublicJobStage"},"type":"array"},{"type":"null"}],"title":"Stages","description":"Ordered Audience stages; null for Playbooks jobs.","examples":[[{"key":"prelim","label":"Preliminary scoring","status":"completed"}]]},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the server accepted the job.","examples":["2026-07-13T12:00:00Z"]},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"When the job input and result leave the 30-day public retention window.","examples":["2026-08-12T12:00:00Z"]},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"When execution began; null while queued.","examples":["2026-07-13T12:00:00Z"]},"finished_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Finished At","description":"When execution reached a terminal state; null while active.","examples":["2026-07-13T12:00:00Z"]},"type":{"type":"string","const":"documents","title":"Type","description":"Discriminator selecting the Documents input and result shapes.","examples":["documents"]},"input":{"$ref":"#/components/schemas/PublicDocumentJobInput","description":"Typed Documents request snapshot retained with the job.","examples":[{"brand":"northstar","brief":"A first-meeting sales proposal for Acme Corporation's RevOps team: lead with their pipeline-visibility pains, map our onboarding time-to-value, and close with a 90-day rollout plan and pricing summary.","document_type":"proposal","external_ref":"crm-account-123","format":"docx","offer":"analytics_suite","target_domain":"acme.example","template_urls":["https://cdn.example/templates/enterprise-proposal.docx"],"title":"Acme Corporation proposal"}]},"result":{"anyOf":[{"$ref":"#/components/schemas/DocumentResult"},{"type":"null"}],"description":"Typed Documents result; null until the job succeeds.","examples":[{"brand":{"key":"northstar","name":"Northstar Analytics","profile_id":"brand_01h8z3m2q7"},"document_type":"proposal","duration_seconds":184.2,"external_ref":"crm-account-123","files":[{"download_path":"/api/orgs/org_123/projects/proj_123/documents/job_document_123/files/docfile_01h8z3m2q7","file_id":"docfile_01h8z3m2q7","filename":"acme-corporation-proposal.docx","format":"docx","size_bytes":48213}],"format":"docx","model":"claude-sonnet-4-6","offer":{"key":"analytics_suite","name":"Analytics Suite","offer_id":"offer_01h8z3m2q7"},"progress":["Session started — analyzing the request...","Searching: acme.example brand colors","Executing document generation code...","Writing: acme-corporation-proposal.docx"],"provenance":{"backend":"anthropic.doc_maker","provider":"anthropic"},"request_echo":"A first-meeting sales proposal for Acme Corporation's RevOps team: lead with their pipeline-visibility pains, map our onboarding time-to-value, and close with a 90-day rollout plan and pricing summary.","schema_version":"2026-07-17","target_domain":"acme.example","title":"Acme Corporation proposal"}]}},"type":"object","required":["id","status","progress","project_id","usage","created_at","expires_at","type","input"],"title":"DocumentJobResponse","description":"A Documents-specific asynchronous job response.","examples":[{"created_at":"2026-07-13T12:00:00Z","expires_at":"2026-08-12T12:00:00Z","finished_at":"2026-07-13T12:00:00Z","id":"job_document_123","input":{"brand":"northstar","brief":"A first-meeting sales proposal for Acme Corporation's RevOps team: lead with their pipeline-visibility pains, map our onboarding time-to-value, and close with a 90-day rollout plan and pricing summary.","document_type":"proposal","external_ref":"crm-account-123","format":"docx","offer":"analytics_suite","target_domain":"acme.example","template_urls":["https://cdn.example/templates/enterprise-proposal.docx"],"title":"Acme Corporation proposal"},"progress":100,"project_id":"proj_123","result":{"brand":{"key":"northstar","name":"Northstar Analytics","profile_id":"brand_01h8z3m2q7"},"document_type":"proposal","duration_seconds":184.2,"external_ref":"crm-account-123","files":[{"download_path":"/api/orgs/org_123/projects/proj_123/documents/job_document_123/files/docfile_01h8z3m2q7","file_id":"docfile_01h8z3m2q7","filename":"acme-corporation-proposal.docx","format":"docx","size_bytes":48213}],"format":"docx","model":"claude-sonnet-4-6","offer":{"key":"analytics_suite","name":"Analytics Suite","offer_id":"offer_01h8z3m2q7"},"progress":["Session started — analyzing the request...","Searching: acme.example brand colors","Executing document generation code...","Writing: acme-corporation-proposal.docx"],"provenance":{"backend":"anthropic.doc_maker","provider":"anthropic"},"request_echo":"A first-meeting sales proposal for Acme Corporation's RevOps team: lead with their pipeline-visibility pains, map our onboarding time-to-value, and close with a 90-day rollout plan and pricing summary.","schema_version":"2026-07-17","target_domain":"acme.example","title":"Acme Corporation proposal"},"stages":[{"key":"prepare","label":"Preparing brand pack & offer","status":"completed"},{"key":"generate","label":"Creating the document","status":"completed"},{"key":"deliver","label":"Delivering files","status":"completed"}],"started_at":"2026-07-13T12:00:00Z","status":"succeeded","type":"documents","usage":{"backend_requests":1,"backend_runtime_ms":1830,"cache_write_tokens":300,"cached_input_tokens":1200,"cost_usd":0.8412,"input_tokens":3500,"output_tokens":700,"reasoning_tokens":180,"tokens":152400}}]},"DocumentOfferRef":{"properties":{"offer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Offer Id","description":"Offer identifier.","examples":["offer_01h8z3m2q7"]},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Offer display name.","examples":["Analytics Suite"]},"key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key","description":"Stable offer key.","examples":["analytics_suite"]}},"type":"object","title":"DocumentOfferRef","description":"The platform offer whose selling substance was attached to this document.","examples":[{"key":"analytics_suite","name":"Analytics Suite","offer_id":"offer_01h8z3m2q7"}]},"DocumentResult":{"properties":{"schema_version":{"type":"string","const":"2026-07-17","title":"Schema Version","description":"Result schema version.","default":"2026-07-17","examples":["2026-07-17"]},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Document title: the caller-supplied title, or one derived from the primary produced file; null only when neither exists.","examples":["Acme Corporation proposal"]},"request_echo":{"type":"string","maxLength":500,"title":"Request Echo","description":"First 500 characters of the caller's brief, echoed for traceability.","examples":["A first-meeting sales proposal for Acme Corporation's RevOps team: lead with their pipeline-visibility pains, map our onboarding time-to-value, and close with a 90-day rollout plan and pricing summary."]},"document_type":{"anyOf":[{"type":"string","enum":["proposal","playbook","deck","gtm_strategy","report","one_pager"]},{"type":"null"}],"title":"Document Type","description":"Requested collateral type; null when the agent chose the type.","examples":["proposal"]},"format":{"anyOf":[{"type":"string","enum":["pptx","docx","pdf"]},{"type":"null"}],"title":"Format","description":"Document format: the requested output format, or the primary produced file's format when the agent chose.","examples":["docx"]},"target_domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Domain","description":"Normalized focus-account domain from the request; null when none was set.","examples":["acme.example"]},"brand":{"anyOf":[{"$ref":"#/components/schemas/DocumentBrandRef"},{"type":"null"}],"description":"Platform brand whose Brand Pack branded the document; null for legacy results.","examples":[{"key":"northstar","name":"Northstar Analytics","profile_id":"brand_01h8z3m2q7"}]},"offer":{"anyOf":[{"$ref":"#/components/schemas/DocumentOfferRef"},{"type":"null"}],"description":"Platform offer attached to the run; null when no offer was attached.","examples":[{"key":"analytics_suite","name":"Analytics Suite","offer_id":"offer_01h8z3m2q7"}]},"files":{"items":{"$ref":"#/components/schemas/DocumentFileRef"},"type":"array","title":"Files","description":"Stored collateral files produced by the run — at least one for real runs. Download bytes via `GET /v1/documents/{job_id}/files/{file_id}`.","examples":[[{"download_path":"/api/orgs/org_123/projects/proj_123/documents/job_document_123/files/docfile_01h8z3m2q7","file_id":"docfile_01h8z3m2q7","filename":"acme-corporation-proposal.docx","format":"docx","size_bytes":48213}]]},"progress":{"items":{"type":"string"},"type":"array","maxItems":50,"title":"Progress","description":"Up to 50 curated agent milestones from the generation session, in order.","examples":[["Session started — analyzing the request...","Searching: acme.example brand colors","Executing document generation code...","Writing: acme-corporation-proposal.docx"]]},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model","description":"Model that ran the generation agent; null when unknown.","examples":["claude-sonnet-4-6"]},"duration_seconds":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Duration Seconds","description":"Wall-clock agent session duration in seconds; null when unknown.","examples":[184.2]},"external_ref":{"anyOf":[{"type":"string","maxLength":240},{"type":"null"}],"title":"External Ref","description":"Caller-supplied correlation reference echoed from the input; null when omitted.","examples":["crm-account-123"]},"provenance":{"additionalProperties":{"type":"string"},"type":"object","title":"Provenance","description":"Backend attribution: provider and backend identifiers.","examples":[{"backend":"anthropic.doc_maker","provider":"anthropic"}]}},"type":"object","required":["request_echo"],"title":"DocumentResult","description":"A completed sales-collateral run: stored file references plus run metadata.","examples":[{"brand":{"key":"northstar","name":"Northstar Analytics","profile_id":"brand_01h8z3m2q7"},"document_type":"proposal","duration_seconds":184.2,"external_ref":"crm-account-123","files":[{"download_path":"/api/orgs/org_123/projects/proj_123/documents/job_document_123/files/docfile_01h8z3m2q7","file_id":"docfile_01h8z3m2q7","filename":"acme-corporation-proposal.docx","format":"docx","size_bytes":48213}],"format":"docx","model":"claude-sonnet-4-6","offer":{"key":"analytics_suite","name":"Analytics Suite","offer_id":"offer_01h8z3m2q7"},"progress":["Session started — analyzing the request...","Searching: acme.example brand colors","Executing document generation code...","Writing: acme-corporation-proposal.docx"],"provenance":{"backend":"anthropic.doc_maker","provider":"anthropic"},"request_echo":"A first-meeting sales proposal for Acme Corporation's RevOps team: lead with their pipeline-visibility pains, map our onboarding time-to-value, and close with a 90-day rollout plan and pricing summary.","schema_version":"2026-07-17","target_domain":"acme.example","title":"Acme Corporation proposal"}]},"EnrichmentField":{"type":"string","enum":["company_description","company_industry","company_headcount","company_latest_funding","person_job_title","person_seniority","work_email","work_email_verification"],"title":"EnrichmentField","description":"Structured enrichmentfield data exposed by the public API.","examples":["company_description"]},"EnrichmentFieldSpecification":{"properties":{"field":{"$ref":"#/components/schemas/EnrichmentField","description":"The field value for this enrichmentfieldspecification.","examples":["company_description"]},"target":{"$ref":"#/components/schemas/EnrichmentTarget","description":"The target value for this enrichmentfieldspecification.","examples":["company"]},"value_type":{"$ref":"#/components/schemas/EnrichmentValueType","description":"The value type value for this enrichmentfieldspecification.","examples":["text"]},"required_connector_capability":{"$ref":"#/components/schemas/app__enrichment_spec_schema__RequiredConnectorCapability","description":"The required connector capability value for this enrichmentfieldspecification.","examples":["people-enrich"]},"max_freshness_days":{"type":"integer","maximum":365.0,"minimum":1.0,"title":"Max Freshness Days","description":"The max freshness days value for this enrichmentfieldspecification.","examples":[1]},"evidence_required":{"type":"boolean","const":true,"title":"Evidence Required","description":"The evidence required value for this enrichmentfieldspecification."}},"additionalProperties":false,"type":"object","required":["field","target","value_type","required_connector_capability","max_freshness_days","evidence_required"],"title":"EnrichmentFieldSpecification","description":"Structured enrichmentfieldspecification data exposed by the public API.","examples":[{"field":"company_description","target":"company","value_type":"text","required_connector_capability":"people-enrich","max_freshness_days":1,"evidence_required":true}]},"EnrichmentSelectionIn":{"properties":{"mode":{"$ref":"#/components/schemas/EnrichmentSelectionMode","description":"The mode value for this enrichmentselectionin.","examples":["included"]},"member_ids":{"items":{"type":"string","pattern":"^audmem_[a-f0-9]{24}$"},"type":"array","maxItems":100,"title":"Member Ids","description":"The member ids value for this enrichmentselectionin.","examples":[["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"]]}},"additionalProperties":false,"type":"object","required":["mode"],"title":"EnrichmentSelectionIn","description":"Select all included members or one exact reviewed subset.","examples":[{"mode":"included"}]},"EnrichmentSelectionMode":{"type":"string","enum":["included","explicit"],"title":"EnrichmentSelectionMode","description":"Structured enrichmentselectionmode data exposed by the public API.","examples":["included"]},"EnrichmentSelectionSnapshot":{"properties":{"mode":{"$ref":"#/components/schemas/EnrichmentSelectionMode","description":"The mode value for this enrichmentselectionsnapshot.","examples":["included"]},"member_ids":{"items":{"type":"string","pattern":"^audmem_[a-f0-9]{24}$"},"type":"array","maxItems":100,"title":"Member Ids","description":"The member ids value for this enrichmentselectionsnapshot.","examples":[["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"]]},"member_count":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Member Count","description":"The member count value for this enrichmentselectionsnapshot.","examples":[1]},"member_snapshot_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Member Snapshot Hash","description":"The member snapshot hash value for this enrichmentselectionsnapshot.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]}},"additionalProperties":false,"type":"object","required":["mode","member_ids","member_count","member_snapshot_hash"],"title":"EnrichmentSelectionSnapshot","description":"Structured enrichmentselectionsnapshot data exposed by the public API.","examples":[{"mode":"included","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"member_count":1,"member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}]},"EnrichmentSpecificationCreateIn":{"properties":{"key":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","title":"Key","description":"The key value for this enrichmentspecificationcreatein.","examples":["example-key"]},"audience_id":{"type":"string","pattern":"^audience_[a-f0-9]{24}$","title":"Audience Id","description":"The audience id value for this enrichmentspecificationcreatein.","examples":["audience_aaaaaaaaaaaaaaaaaaaaaaaa"]},"expected_audience_result_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Expected Audience Result Hash","description":"The expected audience result hash value for this enrichmentspecificationcreatein.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"selection":{"$ref":"#/components/schemas/EnrichmentSelectionIn","description":"The selection value for this enrichmentspecificationcreatein.","examples":[{"mode":"included"}]},"fields":{"items":{"$ref":"#/components/schemas/EnrichmentField"},"type":"array","maxItems":8,"minItems":1,"title":"Fields","description":"The fields value for this enrichmentspecificationcreatein.","examples":[["company_description"]]},"expected_policy_version":{"$ref":"#/components/schemas/EnrichmentSpecificationPolicyVersion","description":"The expected policy version value for this enrichmentspecificationcreatein.","examples":["2026-07-13"]},"reason":{"type":"string","maxLength":500,"minLength":3,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"Reason","description":"The reason value for this enrichmentspecificationcreatein.","examples":["Example value"]}},"additionalProperties":false,"type":"object","required":["key","audience_id","expected_audience_result_hash","selection","fields","expected_policy_version","reason"],"title":"EnrichmentSpecificationCreateIn","description":"Freeze an exact enrichment plan; this input cannot carry code, prompts, URLs, or secrets.","examples":[{"key":"example-key","audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","expected_audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","selection":{"mode":"included"},"fields":["company_description"],"expected_policy_version":"2026-07-13","reason":"Example value"}]},"EnrichmentSpecificationListOut":{"properties":{"specifications":{"items":{"$ref":"#/components/schemas/EnrichmentSpecificationOut"},"type":"array","title":"Specifications","description":"The specifications value for this enrichmentspecificationlistout.","examples":[[{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"enrichspec_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","policy_version":"2026-07-13","selection":{"mode":"included","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"member_count":1,"member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},"field_specs":[{"field":"company_description","target":"company","value_type":"text","required_connector_capability":"people-enrich","max_freshness_days":1,"evidence_required":true}],"specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"provider_requests_made":false,"records_processed":0,"records_enriched":0,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}]]},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"The total value for this enrichmentspecificationlistout.","examples":[0]},"limit":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Limit","description":"The limit value for this enrichmentspecificationlistout.","examples":[1]},"offset":{"type":"integer","maximum":10000.0,"minimum":0.0,"title":"Offset","description":"The offset value for this enrichmentspecificationlistout.","examples":[0]},"availability":{"type":"string","const":"contract_only","title":"Availability","description":"The availability value for this enrichmentspecificationlistout."},"execution_available":{"type":"boolean","const":false,"title":"Execution Available","description":"The execution available value for this enrichmentspecificationlistout."},"provider_requests_made":{"type":"boolean","const":false,"title":"Provider Requests Made","description":"The provider requests made value for this enrichmentspecificationlistout."}},"additionalProperties":false,"type":"object","required":["specifications","total","limit","offset","availability","execution_available","provider_requests_made"],"title":"EnrichmentSpecificationListOut","description":"Structured enrichmentspecificationlistout data exposed by the public API.","examples":[{"specifications":[{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"enrichspec_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","policy_version":"2026-07-13","selection":{"mode":"included","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"member_count":1,"member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},"field_specs":[{"field":"company_description","target":"company","value_type":"text","required_connector_capability":"people-enrich","max_freshness_days":1,"evidence_required":true}],"specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"provider_requests_made":false,"records_processed":0,"records_enriched":0,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}],"total":0,"limit":1,"offset":0,"availability":"contract_only","execution_available":false,"provider_requests_made":false}]},"EnrichmentSpecificationOut":{"properties":{"schema_version":{"$ref":"#/components/schemas/EnrichmentSpecificationSchemaVersion","description":"The schema version value for this enrichmentspecificationout.","examples":["2026-07-13"]},"status":{"type":"string","const":"specified","title":"Status","description":"The status value for this enrichmentspecificationout."},"availability":{"type":"string","const":"contract_only","title":"Availability","description":"The availability value for this enrichmentspecificationout."},"id":{"type":"string","pattern":"^enrichspec_[a-f0-9]{24}$","title":"Id","description":"The id value for this enrichmentspecificationout.","examples":["enrichspec_aaaaaaaaaaaaaaaaaaaaaaaa"]},"idempotent_replay":{"type":"boolean","title":"Idempotent Replay","description":"The idempotent replay value for this enrichmentspecificationout.","examples":[true]},"key":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","title":"Key","description":"The key value for this enrichmentspecificationout.","examples":["example-key"]},"project_id":{"type":"string","pattern":"^proj_[a-f0-9]{24}$","title":"Project Id","description":"The project id value for this enrichmentspecificationout.","examples":["proj_aaaaaaaaaaaaaaaaaaaaaaaa"]},"environment":{"type":"string","enum":["live","test"],"title":"Environment","description":"The environment value for this enrichmentspecificationout.","examples":["live"]},"audience_id":{"type":"string","pattern":"^audience_[a-f0-9]{24}$","title":"Audience Id","description":"The audience id value for this enrichmentspecificationout.","examples":["audience_aaaaaaaaaaaaaaaaaaaaaaaa"]},"audience_result_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Audience Result Hash","description":"The audience result hash value for this enrichmentspecificationout.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"policy_version":{"$ref":"#/components/schemas/EnrichmentSpecificationPolicyVersion","description":"The policy version value for this enrichmentspecificationout.","examples":["2026-07-13"]},"selection":{"$ref":"#/components/schemas/EnrichmentSelectionSnapshot","description":"The selection value for this enrichmentspecificationout.","examples":[{"mode":"included","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"member_count":1,"member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}]},"field_specs":{"items":{"$ref":"#/components/schemas/EnrichmentFieldSpecification"},"type":"array","maxItems":8,"minItems":1,"title":"Field Specs","description":"The field specs value for this enrichmentspecificationout.","examples":[[{"field":"company_description","target":"company","value_type":"text","required_connector_capability":"people-enrich","max_freshness_days":1,"evidence_required":true}]]},"specification_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Specification Hash","description":"The specification hash value for this enrichmentspecificationout.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"reason":{"type":"string","maxLength":500,"minLength":3,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"Reason","description":"The reason value for this enrichmentspecificationout.","examples":["Example value"]},"execution_available":{"type":"boolean","const":false,"title":"Execution Available","description":"The execution available value for this enrichmentspecificationout."},"execution_authorized":{"type":"boolean","const":false,"title":"Execution Authorized","description":"The execution authorized value for this enrichmentspecificationout."},"provider_requests_made":{"type":"boolean","const":false,"title":"Provider Requests Made","description":"The provider requests made value for this enrichmentspecificationout."},"records_processed":{"type":"integer","const":0,"title":"Records Processed","description":"The records processed value for this enrichmentspecificationout."},"records_enriched":{"type":"integer","const":0,"title":"Records Enriched","description":"The records enriched value for this enrichmentspecificationout."},"export_authorized":{"type":"boolean","const":false,"title":"Export Authorized","description":"The export authorized value for this enrichmentspecificationout."},"outbound_authorized":{"type":"boolean","const":false,"title":"Outbound Authorized","description":"The outbound authorized value for this enrichmentspecificationout."},"crm_mutation_authorized":{"type":"boolean","const":false,"title":"Crm Mutation Authorized","description":"The crm mutation authorized value for this enrichmentspecificationout."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"The created at value for this enrichmentspecificationout.","examples":["2026-07-16T00:00:00Z"]}},"additionalProperties":false,"type":"object","required":["schema_version","status","availability","id","idempotent_replay","key","project_id","environment","audience_id","audience_result_hash","policy_version","selection","field_specs","specification_hash","reason","execution_available","execution_authorized","provider_requests_made","records_processed","records_enriched","export_authorized","outbound_authorized","crm_mutation_authorized","created_at"],"title":"EnrichmentSpecificationOut","description":"Persisted contract-only plan. Every execution/effect flag remains false.","examples":[{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"enrichspec_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","policy_version":"2026-07-13","selection":{"mode":"included","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"member_count":1,"member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},"field_specs":[{"field":"company_description","target":"company","value_type":"text","required_connector_capability":"people-enrich","max_freshness_days":1,"evidence_required":true}],"specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"provider_requests_made":false,"records_processed":0,"records_enriched":0,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}]},"EnrichmentSpecificationPolicyVersion":{"type":"string","enum":["2026-07-13"],"title":"EnrichmentSpecificationPolicyVersion","description":"Readable/replayable policies; append versions, never replace them.","examples":["2026-07-13"]},"EnrichmentSpecificationSchemaVersion":{"type":"string","enum":["2026-07-13"],"title":"EnrichmentSpecificationSchemaVersion","description":"Readable historical response schemas; append versions, never replace them.","examples":["2026-07-13"]},"EnrichmentTarget":{"type":"string","enum":["company","person","email"],"title":"EnrichmentTarget","description":"Structured enrichmenttarget data exposed by the public API.","examples":["company"]},"EnrichmentValueType":{"type":"string","enum":["text","integer_range","funding_event","seniority","email","email_verification"],"title":"EnrichmentValueType","description":"Structured enrichmentvaluetype data exposed by the public API.","examples":["text"]},"ErrorBody":{"properties":{"code":{"$ref":"#/components/schemas/PublicErrorCode","description":"Stable machine-readable error code. Branch client handling on this value, not HTTP status alone.","examples":["invalid_request"]},"message":{"type":"string","title":"Message","description":"Human-readable explanation safe to display to an end user.","examples":["The request is malformed or fails input validation."]},"request_id":{"type":"string","title":"Request Id","description":"Request correlation ID. Include it when contacting support.","examples":["req_2c15edb03f3448a3a3bbabdf072cc872"]},"docs_url":{"type":"string","title":"Docs Url","description":"Configured documentation URL for public API errors.","examples":["https://api.blackpearl.com/docs/errors"]},"details":{"anyOf":[{"additionalProperties":true,"type":"object"},{"items":{"$ref":"#/components/schemas/PublicValidationIssue"},"type":"array"},{"type":"null"}],"title":"Details","description":"Optional structured context. Validation failures return an issue list; quota and budget failures return counters and a reset timestamp.","examples":[{}]}},"type":"object","required":["code","message","request_id","docs_url"],"title":"ErrorBody","description":"Stable payload nested under the public API error envelope.","examples":[{"code":"invalid_request","details":[{"loc":["body","target_company"],"msg":"Field required","type":"missing"}],"docs_url":"https://api.blackpearl.com/docs/errors","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872"}]},"ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/ErrorBody","description":"Stable public error details.","examples":[{"code":"invalid_request","details":[{"loc":["body","target_company"],"msg":"Field required","type":"missing"}],"docs_url":"https://api.blackpearl.com/docs/errors","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872"}]}},"type":"object","required":["error"],"title":"ErrorResponse","description":"Stable JSON envelope returned for every public API failure.","examples":[{"error":{"code":"invalid_request","docs_url":"https://api.blackpearl.com/docs/errors","message":"The request is malformed or fails input validation.","request_id":"req_2c15edb03f3448a3a3bbabdf072cc872"}}]},"EvidenceRef":{"properties":{"id":{"type":"string","maxLength":120,"title":"Id","description":"The id value for this evidenceref.","examples":["Example id"]},"source":{"type":"string","enum":["web","provider","crm","user_input"],"title":"Source","description":"The source value for this evidenceref.","examples":["web"]},"label":{"type":"string","maxLength":500,"title":"Label","description":"The label value for this evidenceref.","examples":["Example label"]},"url":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Url","description":"The url value for this evidenceref.","examples":["https://example.com"]},"snippet":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Snippet","description":"The snippet value for this evidenceref.","examples":["Example snippet"]},"observed_at":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Observed At","description":"The observed at value for this evidenceref.","examples":["Example observed at"]},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence","description":"The confidence value for this evidenceref.","examples":[0.0]}},"type":"object","required":["id","source","label","confidence"],"title":"EvidenceRef","description":"Structured evidenceref data exposed by the public API.","examples":[{"id":"Example id","source":"web","label":"Example label","confidence":0.0}]},"EvidenceStatement":{"properties":{"text":{"type":"string","maxLength":1000,"minLength":1,"title":"Text","description":"The text value for this evidencestatement.","examples":["Example text"]},"source_url":{"type":"string","maxLength":2000,"minLength":8,"pattern":"^https?://","title":"Source Url","description":"The source url value for this evidencestatement.","examples":["https://example.com"]},"observed_at":{"type":"string","maxLength":80,"minLength":10,"title":"Observed At","description":"The observed at value for this evidencestatement.","examples":["Example observed at"]},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence","default":1.0,"description":"The confidence value for this evidencestatement."}},"additionalProperties":false,"type":"object","required":["text","source_url","observed_at"],"title":"EvidenceStatement","description":"Structured evidencestatement data exposed by the public API.","examples":[{"text":"Example text","source_url":"https://example.com","observed_at":"Example observed at"}]},"EvidenceUsedOut":{"properties":{"text":{"type":"string","title":"Text","description":"The text value for this evidenceusedout.","examples":["Example text"]},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url","description":"The source url value for this evidenceusedout.","examples":["https://example.com"]},"observed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Observed At","description":"The observed at value for this evidenceusedout.","examples":["Example observed at"]},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence","description":"The confidence value for this evidenceusedout.","examples":[0.0]},"synthetic":{"type":"boolean","title":"Synthetic","default":false,"description":"The synthetic value for this evidenceusedout."}},"additionalProperties":false,"type":"object","required":["text","confidence"],"title":"EvidenceUsedOut","description":"Structured evidenceusedout data exposed by the public API.","examples":[{"text":"Example text","confidence":0.0}]},"FetchResourcePolicy":{"properties":{"resource":{"type":"string","enum":["root_html","robots_txt","sitemap_xml"],"title":"Resource","description":"The resource value for this fetchresourcepolicy.","examples":["root_html"]},"path":{"type":"string","enum":["/","/robots.txt","/sitemap.xml"],"title":"Path","description":"The path value for this fetchresourcepolicy.","examples":["/"]},"maximum_bytes":{"type":"integer","maximum":2097152.0,"minimum":1.0,"title":"Maximum Bytes","description":"The maximum bytes value for this fetchresourcepolicy.","examples":[1]},"allowed_content_types":{"items":{"type":"string"},"type":"array","maxItems":3,"minItems":1,"title":"Allowed Content Types","description":"The allowed content types value for this fetchresourcepolicy.","examples":[["Example allowed content types"]]}},"additionalProperties":false,"type":"object","required":["resource","path","maximum_bytes","allowed_content_types"],"title":"FetchResourcePolicy","description":"Structured fetchresourcepolicy data exposed by the public API.","examples":[{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]}]},"FocusImageAsset":{"properties":{"name":{"type":"string","maxLength":160,"title":"Name","description":"The name value for this focusimageasset.","examples":["Example name"]},"url":{"type":"string","maxLength":2000,"title":"Url","description":"The url value for this focusimageasset.","examples":["https://example.com"]},"kind":{"type":"string","enum":["hero","banner","feature","product","editorial","other"],"title":"Kind","default":"feature","description":"The kind value for this focusimageasset."},"alt_text":{"type":"string","maxLength":500,"title":"Alt Text","description":"The alt text value for this focusimageasset.","examples":["Example alt text"]},"usage_notes":{"anyOf":[{"type":"string","maxLength":600},{"type":"null"}],"title":"Usage Notes","description":"The usage notes value for this focusimageasset.","examples":["Example usage notes"]},"source_id":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Source Id","description":"The source id value for this focusimageasset.","examples":["Example source id"]}},"additionalProperties":false,"type":"object","required":["name","url","alt_text"],"title":"FocusImageAsset","description":"Structured focusimageasset data exposed by the public API.","examples":[{"name":"Example name","url":"https://example.com","alt_text":"Example alt text"}]},"FontFaceAsset":{"properties":{"url":{"type":"string","maxLength":2000,"title":"Url","description":"The url value for this fontfaceasset.","examples":["https://example.com"]},"format":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"title":"Format","description":"The format value for this fontfaceasset.","examples":["Example format"]},"weight":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"title":"Weight","description":"The weight value for this fontfaceasset.","examples":["Example weight"]},"style":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"title":"Style","description":"The style value for this fontfaceasset.","examples":["Example style"]},"unicode_range":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Unicode Range","description":"The unicode range value for this fontfaceasset.","examples":["Example unicode range"]}},"additionalProperties":false,"type":"object","required":["url"],"title":"FontFaceAsset","description":"Structured fontfaceasset data exposed by the public API.","examples":[{"url":"https://example.com"}]},"GeneratedTemplateResult":{"properties":{"schema_version":{"type":"string","const":"2026-07-20","title":"Schema Version","default":"2026-07-20","description":"The schema version value for this generatedtemplateresult."},"operation":{"type":"string","const":"template_generation","title":"Operation","default":"template_generation","description":"The operation value for this generatedtemplateresult."},"status":{"type":"string","const":"DRAFT_READY","title":"Status","default":"DRAFT_READY","description":"The status value for this generatedtemplateresult."},"revision":{"$ref":"#/components/schemas/MessageTemplateRevisionOut","description":"The revision value for this generatedtemplateresult.","examples":[{"schema_version":"2026-07-13","status":"active","availability":"render_only","id":"msgtemplate_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"template_key":"example-key","revision_number":1,"name":"Example value","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","channel":"email","purpose":"gtm_outreach","language":"en-nz","variables":[{"key":"contact.firstname","classification":"recipient_personal","required":true,"max_length":1}],"subject":[{"kind":"text","text":"Example text"}],"body":[{"kind":"paragraph","content":[{"kind":"text","text":"Example text"}]},{"kind":"paragraph","content":[{"kind":"text","text":"Example text"}]}],"policy_version":"2026-07-13","template_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","previous_revision_id":"msgtemplate_aaaaaaaaaaaaaaaaaaaaaaaa","previous_template_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","arbitrary_template_code_accepted":false,"raw_html_accepted":false,"variable_values_stored":false,"attachment_uploads_accepted":false,"tracking_enabled":false,"provider_requests_made":0,"messages_enqueued":0,"messages_sent":0,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}]},"quality":{"$ref":"#/components/schemas/QualityScore","description":"The quality value for this generatedtemplateresult.","examples":[{"relevance":0,"evidence":0,"clarity":0,"recipient_value":0,"cta":0,"trust":0,"mobile_readability":0,"total":0,"passed":true}]},"rationale":{"type":"string","maxLength":2000,"title":"Rationale","description":"The rationale value for this generatedtemplateresult.","examples":["Example rationale"]},"approval_required":{"type":"boolean","const":true,"title":"Approval Required","default":true,"description":"The approval required value for this generatedtemplateresult."},"messages_enqueued":{"type":"integer","const":0,"title":"Messages Enqueued","default":0,"description":"The messages enqueued value for this generatedtemplateresult."},"messages_sent":{"type":"integer","const":0,"title":"Messages Sent","default":0,"description":"The messages sent value for this generatedtemplateresult."},"outbound_authorized":{"type":"boolean","const":false,"title":"Outbound Authorized","default":false,"description":"The outbound authorized value for this generatedtemplateresult."}},"additionalProperties":false,"type":"object","required":["revision","quality","rationale"],"title":"GeneratedTemplateResult","description":"Structured generatedtemplateresult data exposed by the public API.","examples":[{"revision":{"schema_version":"2026-07-13","status":"active","availability":"render_only","id":"msgtemplate_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"template_key":"example-key","revision_number":1,"name":"Example value","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","channel":"email","purpose":"gtm_outreach","language":"en-nz","variables":[{"key":"contact.firstname","classification":"recipient_personal","required":true,"max_length":1}],"subject":[{"kind":"text","text":"Example text"}],"body":[{"kind":"paragraph","content":[{"kind":"text","text":"Example text"}]},{"kind":"paragraph","content":[{"kind":"text","text":"Example text"}]}],"policy_version":"2026-07-13","template_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","previous_revision_id":"msgtemplate_aaaaaaaaaaaaaaaaaaaaaaaa","previous_template_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","arbitrary_template_code_accepted":false,"raw_html_accepted":false,"variable_values_stored":false,"attachment_uploads_accepted":false,"tracking_enabled":false,"provider_requests_made":0,"messages_enqueued":0,"messages_sent":0,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"},"quality":{"relevance":0,"evidence":0,"clarity":0,"recipient_value":0,"cta":0,"trust":0,"mobile_readability":0,"total":0,"passed":true},"rationale":"Example rationale"}]},"GuidelineGeneration":{"properties":{"provider":{"type":"string","enum":["openai","legacy_import"],"title":"Provider","description":"The provider value for this guidelinegeneration.","examples":["openai"]},"model":{"type":"string","title":"Model","description":"The model value for this guidelinegeneration.","examples":["Example model"]},"workflow":{"type":"string","title":"Workflow","default":"brand_guideline_research","description":"The workflow value for this guidelinegeneration."}},"additionalProperties":false,"type":"object","required":["provider","model"],"title":"GuidelineGeneration","description":"Structured guidelinegeneration data exposed by the public API.","examples":[{"provider":"openai","model":"Example model"}]},"IntakeField":{"type":"string","enum":["source_record_id","provider_identifier","license_identifier","organization_name","organization_alias","website_url","business_phone","postal_address","locality","region_code","postal_code","country_code","latitude","longitude","industry_category","industry_code","organization_status"],"title":"IntakeField","description":"Structured intakefield data exposed by the public API.","examples":["source_record_id"]},"IntakePurpose":{"type":"string","enum":["account_discovery","data_quality_review","firmographic_enrichment","registry_reconciliation"],"title":"IntakePurpose","description":"Structured intakepurpose data exposed by the public API.","examples":["account_discovery"]},"IntakeValueType":{"type":"string","enum":["identifier","text","url","phone","postal_address","country_subdivision","postal_code","country_code","decimal_degrees","category","status"],"title":"IntakeValueType","description":"Structured intakevaluetype data exposed by the public API.","examples":["identifier"]},"LogoAsset":{"properties":{"name":{"type":"string","maxLength":160,"title":"Name","description":"The name value for this logoasset.","examples":["Example name"]},"url":{"type":"string","maxLength":2000,"title":"Url","description":"The url value for this logoasset.","examples":["https://example.com"]},"format":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"title":"Format","description":"The format value for this logoasset.","examples":["Example format"]},"variant":{"type":"string","maxLength":100,"title":"Variant","description":"The variant value for this logoasset.","examples":["Example variant"]},"best_on":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Best On","description":"The best on value for this logoasset.","examples":["Example best on"]},"usage_notes":{"anyOf":[{"type":"string","maxLength":600},{"type":"null"}],"title":"Usage Notes","description":"The usage notes value for this logoasset.","examples":["Example usage notes"]},"source_id":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Source Id","description":"The source id value for this logoasset.","examples":["Example source id"]}},"additionalProperties":false,"type":"object","required":["name","url","variant"],"title":"LogoAsset","description":"Structured logoasset data exposed by the public API.","examples":[{"name":"Example name","url":"https://example.com","variant":"Example variant"}]},"MessageApprovalArtifact":{"properties":{"artifact_kind":{"type":"string","const":"personalized_message","title":"Artifact Kind","default":"personalized_message","description":"The artifact kind value for this messageapprovalartifact."},"artifact_id":{"type":"string","pattern":"^msgart_[a-f0-9]{64}$","title":"Artifact Id","description":"The artifact id value for this messageapprovalartifact.","examples":["msgart_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"artifact_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Artifact Hash","description":"The artifact hash value for this messageapprovalartifact.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"artifact_version":{"type":"string","const":"2026-07-20","title":"Artifact Version","default":"2026-07-20","description":"The artifact version value for this messageapprovalartifact."}},"additionalProperties":false,"type":"object","required":["artifact_id","artifact_hash"],"title":"MessageApprovalArtifact","description":"Structured messageapprovalartifact data exposed by the public API.","examples":[{"artifact_id":"msgart_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","artifact_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}]},"MessageGenerationJobError":{"properties":{"code":{"type":"string","pattern":"^[a-z][a-z0-9_]*$","title":"Code","description":"Stable machine-readable asynchronous failure code.","examples":["message_template_quality_failed"]},"message":{"type":"string","title":"Message","description":"Safe human-readable terminal failure message.","examples":["The generated template did not pass the published quality gate."]}},"additionalProperties":false,"type":"object","required":["code","message"],"title":"MessageGenerationJobError","description":"Stable terminal failure exposed to message-generation polling clients.","example":{"code":"message_template_quality_failed","message":"The generated template did not pass the published quality gate."}},"MessageTemplateGenerateIn":{"properties":{"operation":{"type":"string","const":"template_generation","title":"Operation","default":"template_generation","description":"The operation value for this messagetemplategeneratein."},"environment":{"type":"string","enum":["live","test"],"title":"Environment","default":"live","description":"The environment value for this messagetemplategeneratein."},"template_key":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","title":"Template Key","description":"The template key value for this messagetemplategeneratein.","examples":["example-key"]},"name":{"type":"string","maxLength":120,"minLength":1,"title":"Name","description":"The name value for this messagetemplategeneratein.","examples":["Example name"]},"language":{"type":"string","maxLength":24,"minLength":2,"pattern":"^[a-z]{2,3}(?:-[a-z0-9]{2,8}){0,2}$","title":"Language","default":"en","description":"The language value for this messagetemplategeneratein."},"audience":{"type":"string","maxLength":4000,"minLength":1,"title":"Audience","description":"The audience value for this messagetemplategeneratein.","examples":["Example audience"]},"objective":{"type":"string","maxLength":4000,"minLength":1,"title":"Objective","description":"The objective value for this messagetemplategeneratein.","examples":["Example objective"]},"offer_id":{"anyOf":[{"type":"string","maxLength":80,"minLength":1},{"type":"null"}],"title":"Offer Id","description":"The offer id value for this messagetemplategeneratein.","examples":["Example offer id"]},"brand_profile_id":{"anyOf":[{"type":"string","maxLength":80,"minLength":1},{"type":"null"}],"title":"Brand Profile Id","description":"The brand profile id value for this messagetemplategeneratein.","examples":["Example brand profile id"]},"campaign_id":{"anyOf":[{"type":"string","maxLength":80,"minLength":1},{"type":"null"}],"title":"Campaign Id","description":"The campaign id value for this messagetemplategeneratein.","examples":["Example campaign id"]},"offer_summary":{"anyOf":[{"type":"string","maxLength":4000,"minLength":1},{"type":"null"}],"title":"Offer Summary","description":"The offer summary value for this messagetemplategeneratein.","examples":["Example offer summary"]},"desired_next_step":{"type":"string","maxLength":500,"minLength":1,"title":"Desired Next Step","description":"The desired next step value for this messagetemplategeneratein.","examples":["Example desired next step"]},"expected_previous_template_hash":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{64}$"},{"type":"null"}],"title":"Expected Previous Template Hash","description":"The expected previous template hash value for this messagetemplategeneratein.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"options":{"$ref":"#/components/schemas/TemplateGenerationOptions","description":"The options value for this messagetemplategeneratein.","examples":[{}]},"reason":{"type":"string","maxLength":500,"minLength":3,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"Reason","description":"The reason value for this messagetemplategeneratein.","examples":["Example value"]}},"additionalProperties":false,"type":"object","required":["template_key","name","audience","objective","desired_next_step","reason"],"title":"MessageTemplateGenerateIn","description":"Create the next immutable template revision with an OpenAI drafting job.","examples":[{"template_key":"example-key","name":"Example name","audience":"Example audience","objective":"Example objective","desired_next_step":"Example desired next step","reason":"Example value"}]},"MessageTemplateGenerationConfigOut":{"properties":{"operation":{"type":"string","const":"template_generation","title":"Operation","description":"The operation value for this messagetemplategenerationconfigout."},"environment":{"type":"string","enum":["live","test"],"title":"Environment","description":"The environment value for this messagetemplategenerationconfigout.","examples":["live"]},"template_key":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","title":"Template Key","description":"The template key value for this messagetemplategenerationconfigout.","examples":["example-key"]},"name":{"type":"string","maxLength":120,"minLength":1,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"Name","description":"The name value for this messagetemplategenerationconfigout.","examples":["Example value"]},"language":{"type":"string","maxLength":24,"minLength":2,"pattern":"^[a-z]{2,3}(?:-[a-z0-9]{2,8}){0,2}$","title":"Language","description":"The language value for this messagetemplategenerationconfigout.","examples":["en-nz"]},"audience":{"type":"string","maxLength":4000,"minLength":1,"title":"Audience","description":"The audience value for this messagetemplategenerationconfigout.","examples":["Example audience"]},"objective":{"type":"string","maxLength":4000,"minLength":1,"title":"Objective","description":"The objective value for this messagetemplategenerationconfigout.","examples":["Example objective"]},"offer_id":{"anyOf":[{"type":"string","maxLength":80,"minLength":1},{"type":"null"}],"title":"Offer Id","description":"The offer id value for this messagetemplategenerationconfigout.","examples":["Example offer id"]},"brand_profile_id":{"anyOf":[{"type":"string","maxLength":80,"minLength":1},{"type":"null"}],"title":"Brand Profile Id","description":"The brand profile id value for this messagetemplategenerationconfigout.","examples":["Example brand profile id"]},"campaign_id":{"anyOf":[{"type":"string","maxLength":80,"minLength":1},{"type":"null"}],"title":"Campaign Id","description":"The campaign id value for this messagetemplategenerationconfigout.","examples":["Example campaign id"]},"offer_summary":{"anyOf":[{"type":"string","maxLength":4000,"minLength":1},{"type":"null"}],"title":"Offer Summary","description":"The offer summary value for this messagetemplategenerationconfigout.","examples":["Example offer summary"]},"desired_next_step":{"type":"string","maxLength":500,"minLength":1,"title":"Desired Next Step","description":"The desired next step value for this messagetemplategenerationconfigout.","examples":["Example desired next step"]},"expected_previous_template_hash":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{64}$"},{"type":"null"}],"title":"Expected Previous Template Hash","description":"The expected previous template hash value for this messagetemplategenerationconfigout.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"options":{"$ref":"#/components/schemas/MessageTemplateGenerationOptionsOut","description":"The options value for this messagetemplategenerationconfigout.","examples":[{"tone":"direct","max_words":50,"max_links":0,"allowed_claims":["Example allowed claims"],"forbidden_claims":["Example forbidden claims"],"preferred_terms":["Example preferred terms"],"forbidden_terms":["Example forbidden terms"]}]}},"additionalProperties":false,"type":"object","required":["operation","environment","template_key","name","language","audience","objective","desired_next_step","options"],"title":"MessageTemplateGenerationConfigOut","description":"Typed, non-secret brief snapshot for one AI-created revision.","examples":[{"operation":"template_generation","environment":"live","template_key":"example-key","name":"Example value","language":"en-nz","audience":"Example audience","objective":"Example objective","desired_next_step":"Example desired next step","options":{"tone":"direct","max_words":50,"max_links":0,"allowed_claims":["Example allowed claims"],"forbidden_claims":["Example forbidden claims"],"preferred_terms":["Example preferred terms"],"forbidden_terms":["Example forbidden terms"]}}]},"MessageTemplateGenerationOptionsOut":{"properties":{"tone":{"type":"string","enum":["direct","warm","consultative","technical"],"title":"Tone","description":"The tone value for this messagetemplategenerationoptionsout.","examples":["direct"]},"locale":{"anyOf":[{"type":"string","maxLength":80,"minLength":2},{"type":"null"}],"title":"Locale","description":"The locale value for this messagetemplategenerationoptionsout.","examples":["Example locale"]},"max_words":{"type":"integer","maximum":120.0,"minimum":50.0,"title":"Max Words","description":"The max words value for this messagetemplategenerationoptionsout.","examples":[50]},"max_links":{"type":"integer","maximum":1.0,"minimum":0.0,"title":"Max Links","description":"The max links value for this messagetemplategenerationoptionsout.","examples":[0]},"allowed_claims":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Allowed Claims","description":"The allowed claims value for this messagetemplategenerationoptionsout.","examples":[["Example allowed claims"]]},"forbidden_claims":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Forbidden Claims","description":"The forbidden claims value for this messagetemplategenerationoptionsout.","examples":[["Example forbidden claims"]]},"preferred_terms":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Preferred Terms","description":"The preferred terms value for this messagetemplategenerationoptionsout.","examples":[["Example preferred terms"]]},"forbidden_terms":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Forbidden Terms","description":"The forbidden terms value for this messagetemplategenerationoptionsout.","examples":[["Example forbidden terms"]]},"notes":{"anyOf":[{"type":"string","maxLength":4000,"minLength":1},{"type":"null"}],"title":"Notes","description":"The notes value for this messagetemplategenerationoptionsout.","examples":["Example notes"]}},"additionalProperties":false,"type":"object","required":["tone","max_words","max_links","allowed_claims","forbidden_claims","preferred_terms","forbidden_terms"],"title":"MessageTemplateGenerationOptionsOut","description":"Closed copy-control snapshot retained with an AI-created revision.","examples":[{"tone":"direct","max_words":50,"max_links":0,"allowed_claims":["Example allowed claims"],"forbidden_claims":["Example forbidden claims"],"preferred_terms":["Example preferred terms"],"forbidden_terms":["Example forbidden terms"]}]},"MessageTemplateJobResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Stable asynchronous job identifier.","examples":["job_playbook_123"]},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"],"title":"Status","description":"Current job state.","examples":["succeeded"]},"progress":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Progress","description":"Coarse completion percentage. Terminal successful jobs report 100.","examples":[100]},"project_id":{"type":"string","title":"Project Id","description":"Project that owns the job and its usage.","examples":["proj_123"]},"campaign_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Campaign Id","description":"Owning Audience campaign; null for Playbooks jobs.","examples":["camp_123"]},"error":{"anyOf":[{"$ref":"#/components/schemas/MessageGenerationJobError"},{"type":"null"}],"description":"Stable terminal error code and message; null unless the job failed.","examples":[{"code":"message_template_quality_failed","message":"The generated template did not pass the published quality gate."}]},"error_code":{"anyOf":[{"$ref":"#/components/schemas/PublicErrorCode"},{"type":"null"}],"description":"Stable machine-readable public failure code when one applies; null otherwise.","examples":["insufficient_credits"]},"usage":{"$ref":"#/components/schemas/PublicJobUsage","description":"Usage attributed to this job.","examples":[{"backend_requests":1,"backend_runtime_ms":1830,"cache_write_tokens":300,"cached_input_tokens":1200,"cost_usd":0.0123,"input_tokens":3500,"output_tokens":700,"reasoning_tokens":180,"tokens":4200}]},"stages":{"anyOf":[{"items":{"$ref":"#/components/schemas/PublicJobStage"},"type":"array"},{"type":"null"}],"title":"Stages","description":"Ordered Audience stages; null for Playbooks jobs.","examples":[[{"key":"prelim","label":"Preliminary scoring","status":"completed"}]]},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the server accepted the job.","examples":["2026-07-13T12:00:00Z"]},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"When the job input and result leave the 30-day public retention window.","examples":["2026-08-12T12:00:00Z"]},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"When execution began; null while queued.","examples":["2026-07-13T12:00:00Z"]},"finished_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Finished At","description":"When execution reached a terminal state; null while active.","examples":["2026-07-13T12:00:00Z"]},"type":{"type":"string","const":"message_templates","title":"Type","description":"Discriminator selecting the Message Templates job shape.","examples":["message_templates"]},"input":{"oneOf":[{"$ref":"#/components/schemas/MessageTemplateGenerateIn"},{"$ref":"#/components/schemas/ProspectMessageGenerateIn"}],"title":"Input","description":"Typed template-generation or prospect-personalization input retained for 30 days.","discriminator":{"propertyName":"operation","mapping":{"prospect_personalization":"#/components/schemas/ProspectMessageGenerateIn","template_generation":"#/components/schemas/MessageTemplateGenerateIn"}},"examples":[{"template_key":"example-key","name":"Example name","audience":"Example audience","objective":"Example objective","desired_next_step":"Example desired next step","reason":"Example value"}]},"result":{"anyOf":[{"oneOf":[{"$ref":"#/components/schemas/GeneratedTemplateResult"},{"$ref":"#/components/schemas/ProspectMessageResult"}],"discriminator":{"propertyName":"operation","mapping":{"prospect_personalization":"#/components/schemas/ProspectMessageResult","template_generation":"#/components/schemas/GeneratedTemplateResult"}}},{"type":"null"}],"title":"Result","description":"Immutable template revision or no-send personalized artifact; null until completion.","examples":[{"revision":{"schema_version":"2026-07-13","status":"active","availability":"render_only","id":"msgtemplate_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"template_key":"example-key","revision_number":1,"name":"Example value","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","channel":"email","purpose":"gtm_outreach","language":"en-nz","variables":[{"key":"contact.firstname","classification":"recipient_personal","required":true,"max_length":1}],"subject":[{"kind":"text","text":"Example text"}],"body":[{"kind":"paragraph","content":[{"kind":"text","text":"Example text"}]},{"kind":"paragraph","content":[{"kind":"text","text":"Example text"}]}],"policy_version":"2026-07-13","template_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","previous_revision_id":"msgtemplate_aaaaaaaaaaaaaaaaaaaaaaaa","previous_template_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","arbitrary_template_code_accepted":false,"raw_html_accepted":false,"variable_values_stored":false,"attachment_uploads_accepted":false,"tracking_enabled":false,"provider_requests_made":0,"messages_enqueued":0,"messages_sent":0,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"},"quality":{"relevance":0,"evidence":0,"clarity":0,"recipient_value":0,"cta":0,"trust":0,"mobile_readability":0,"total":0,"passed":true},"rationale":"Example rationale"}]}},"type":"object","required":["id","status","progress","project_id","usage","created_at","expires_at","type","input"],"title":"MessageTemplateJobResponse","description":"An approval-only template generation or prospect-personalization job.","examples":[{"id":"job_playbook_123","status":"succeeded","progress":100,"project_id":"proj_123","usage":{"backend_requests":1,"backend_runtime_ms":1830,"cache_write_tokens":300,"cached_input_tokens":1200,"cost_usd":0.0123,"input_tokens":3500,"output_tokens":700,"reasoning_tokens":180,"tokens":4200},"created_at":"2026-07-13T12:00:00Z","expires_at":"2026-08-12T12:00:00Z","type":"message_templates","input":{"template_key":"example-key","name":"Example name","audience":"Example audience","objective":"Example objective","desired_next_step":"Example desired next step","reason":"Example value"}}]},"MessageTemplatePolicyVersion":{"type":"string","enum":["2026-07-13"],"title":"MessageTemplatePolicyVersion","description":"Readable/replayable renderer policies; append versions, never replace them.","examples":["2026-07-13"]},"MessageTemplateRenderIn":{"properties":{"reference":{"type":"string","maxLength":100,"minLength":1,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,99}$","title":"Reference","description":"The reference value for this messagetemplaterenderin.","examples":["example-key"]},"expected_template_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Expected Template Hash","description":"The expected template hash value for this messagetemplaterenderin.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"values":{"patternProperties":{"^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9]*)*$":{"type":"string","maxLength":2000}},"propertyNames":{"maxLength":80,"minLength":1},"type":"object","maxProperties":32,"title":"Values","description":"The values value for this messagetemplaterenderin.","examples":[{}]},"expected_policy_version":{"$ref":"#/components/schemas/MessageTemplatePolicyVersion","description":"The expected policy version value for this messagetemplaterenderin.","examples":["2026-07-13"]},"fail_closed_on_error":{"type":"boolean","const":true,"title":"Fail Closed On Error","description":"The fail closed on error value for this messagetemplaterenderin."}},"additionalProperties":false,"type":"object","required":["reference","expected_template_hash","values","expected_policy_version","fail_closed_on_error"],"title":"MessageTemplateRenderIn","description":"Render one exact artifact without storing context or authorizing an effect.","examples":[{"reference":"example-key","expected_template_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","values":{},"expected_policy_version":"2026-07-13","fail_closed_on_error":true}]},"MessageTemplateRenderOut":{"properties":{"schema_version":{"$ref":"#/components/schemas/MessageTemplateSchemaVersion","description":"The schema version value for this messagetemplaterenderout.","examples":["2026-07-13"]},"status":{"type":"string","const":"rendered","title":"Status","description":"The status value for this messagetemplaterenderout."},"availability":{"type":"string","const":"render_only","title":"Availability","description":"The availability value for this messagetemplaterenderout."},"reference":{"type":"string","maxLength":100,"minLength":1,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,99}$","title":"Reference","description":"The reference value for this messagetemplaterenderout.","examples":["example-key"]},"project_id":{"type":"string","pattern":"^proj_[a-f0-9]{24}$","title":"Project Id","description":"The project id value for this messagetemplaterenderout.","examples":["proj_aaaaaaaaaaaaaaaaaaaaaaaa"]},"environment":{"type":"string","enum":["live","test"],"title":"Environment","description":"The environment value for this messagetemplaterenderout.","examples":["live"]},"template_revision_id":{"type":"string","pattern":"^msgtemplate_[a-f0-9]{24}$","title":"Template Revision Id","description":"The template revision id value for this messagetemplaterenderout.","examples":["msgtemplate_aaaaaaaaaaaaaaaaaaaaaaaa"]},"template_key":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","title":"Template Key","description":"The template key value for this messagetemplaterenderout.","examples":["example-key"]},"revision_number":{"type":"integer","maximum":1000.0,"minimum":1.0,"title":"Revision Number","description":"The revision number value for this messagetemplaterenderout.","examples":[1]},"language":{"type":"string","maxLength":24,"minLength":2,"pattern":"^[a-z]{2,3}(?:-[a-z0-9]{2,8}){0,2}$","title":"Language","description":"The language value for this messagetemplaterenderout.","examples":["en-nz"]},"policy_version":{"$ref":"#/components/schemas/MessageTemplatePolicyVersion","description":"The policy version value for this messagetemplaterenderout.","examples":["2026-07-13"]},"template_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Template Hash","description":"The template hash value for this messagetemplaterenderout.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"subject":{"type":"string","maxLength":200,"minLength":1,"title":"Subject","description":"The subject value for this messagetemplaterenderout.","examples":["Example subject"]},"text_body":{"type":"string","maxLength":10000,"minLength":1,"title":"Text Body","description":"The text body value for this messagetemplaterenderout.","examples":["Example text body"]},"html_body":{"type":"string","maxLength":20000,"minLength":1,"title":"Html Body","description":"The html body value for this messagetemplaterenderout.","examples":["Example html body"]},"values_used":{"items":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9]*)*$"},"type":"array","maxItems":32,"title":"Values Used","description":"The values used value for this messagetemplaterenderout.","examples":[["contact.firstname"]]},"missing_optional_variables":{"items":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9]*)*$"},"type":"array","maxItems":32,"title":"Missing Optional Variables","description":"The missing optional variables value for this messagetemplaterenderout.","examples":[["contact.firstname"]]},"opt_out_notice_included":{"type":"boolean","const":true,"title":"Opt Out Notice Included","description":"The opt out notice included value for this messagetemplaterenderout."},"variable_values_escaped_for_html":{"type":"boolean","const":true,"title":"Variable Values Escaped For Html","description":"The variable values escaped for html value for this messagetemplaterenderout."},"fail_closed_on_error":{"type":"boolean","const":true,"title":"Fail Closed On Error","description":"The fail closed on error value for this messagetemplaterenderout."},"approval_artifact":{"$ref":"#/components/schemas/ApprovalArtifactOut","description":"The approval artifact value for this messagetemplaterenderout.","examples":[{"artifact_kind":"message","artifact_id":"msgart_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","artifact_version":"2026-07-13","artifact_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}]},"arbitrary_template_code_accepted":{"type":"boolean","const":false,"title":"Arbitrary Template Code Accepted","description":"The arbitrary template code accepted value for this messagetemplaterenderout."},"raw_html_accepted":{"type":"boolean","const":false,"title":"Raw Html Accepted","description":"The raw html accepted value for this messagetemplaterenderout."},"variable_values_stored":{"type":"boolean","const":false,"title":"Variable Values Stored","description":"The variable values stored value for this messagetemplaterenderout."},"attachment_uploads_accepted":{"type":"boolean","const":false,"title":"Attachment Uploads Accepted","description":"The attachment uploads accepted value for this messagetemplaterenderout."},"tracking_enabled":{"type":"boolean","const":false,"title":"Tracking Enabled","description":"The tracking enabled value for this messagetemplaterenderout."},"provider_requests_made":{"type":"integer","const":0,"title":"Provider Requests Made","description":"The provider requests made value for this messagetemplaterenderout."},"messages_enqueued":{"type":"integer","const":0,"title":"Messages Enqueued","description":"The messages enqueued value for this messagetemplaterenderout."},"messages_sent":{"type":"integer","const":0,"title":"Messages Sent","description":"The messages sent value for this messagetemplaterenderout."},"outbound_authorized":{"type":"boolean","const":false,"title":"Outbound Authorized","description":"The outbound authorized value for this messagetemplaterenderout."},"crm_mutation_authorized":{"type":"boolean","const":false,"title":"Crm Mutation Authorized","description":"The crm mutation authorized value for this messagetemplaterenderout."},"rendered_at":{"type":"string","format":"date-time","title":"Rendered At","description":"The rendered at value for this messagetemplaterenderout.","examples":["2026-07-16T00:00:00Z"]}},"additionalProperties":false,"type":"object","required":["schema_version","status","availability","reference","project_id","environment","template_revision_id","template_key","revision_number","language","policy_version","template_hash","subject","text_body","html_body","values_used","missing_optional_variables","opt_out_notice_included","variable_values_escaped_for_html","fail_closed_on_error","approval_artifact","arbitrary_template_code_accepted","raw_html_accepted","variable_values_stored","attachment_uploads_accepted","tracking_enabled","provider_requests_made","messages_enqueued","messages_sent","outbound_authorized","crm_mutation_authorized","rendered_at"],"title":"MessageTemplateRenderOut","description":"Structured messagetemplaterenderout data exposed by the public API.","examples":[{"schema_version":"2026-07-13","status":"rendered","availability":"render_only","reference":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","template_revision_id":"msgtemplate_aaaaaaaaaaaaaaaaaaaaaaaa","template_key":"example-key","revision_number":1,"language":"en-nz","policy_version":"2026-07-13","template_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","subject":"Example subject","text_body":"Example text body","html_body":"Example html body","values_used":["contact.firstname"],"missing_optional_variables":["contact.firstname"],"opt_out_notice_included":true,"variable_values_escaped_for_html":true,"fail_closed_on_error":true,"approval_artifact":{"artifact_kind":"message","artifact_id":"msgart_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","artifact_version":"2026-07-13","artifact_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},"arbitrary_template_code_accepted":false,"raw_html_accepted":false,"variable_values_stored":false,"attachment_uploads_accepted":false,"tracking_enabled":false,"provider_requests_made":0,"messages_enqueued":0,"messages_sent":0,"outbound_authorized":false,"crm_mutation_authorized":false,"rendered_at":"2026-07-16T00:00:00Z"}]},"MessageTemplateRevisionCreateIn":{"properties":{"template_key":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","title":"Template Key","description":"The template key value for this messagetemplaterevisioncreatein.","examples":["example-key"]},"revision_number":{"type":"integer","maximum":1000.0,"minimum":1.0,"title":"Revision Number","description":"The revision number value for this messagetemplaterevisioncreatein.","examples":[1]},"name":{"type":"string","maxLength":120,"minLength":1,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"Name","description":"The name value for this messagetemplaterevisioncreatein.","examples":["Example value"]},"channel":{"type":"string","const":"email","title":"Channel","description":"The channel value for this messagetemplaterevisioncreatein."},"purpose":{"type":"string","const":"gtm_outreach","title":"Purpose","description":"The purpose value for this messagetemplaterevisioncreatein."},"language":{"type":"string","maxLength":24,"minLength":2,"pattern":"^[a-z]{2,3}(?:-[a-z0-9]{2,8}){0,2}$","title":"Language","description":"The language value for this messagetemplaterevisioncreatein.","examples":["en-nz"]},"variables":{"items":{"$ref":"#/components/schemas/VariableDefinition"},"type":"array","maxItems":32,"title":"Variables","description":"The variables value for this messagetemplaterevisioncreatein.","examples":[[{"key":"contact.firstname","classification":"recipient_personal","required":true,"max_length":1}]]},"subject":{"items":{"oneOf":[{"$ref":"#/components/schemas/TextInline"},{"$ref":"#/components/schemas/VariableInline"},{"$ref":"#/components/schemas/ConditionInline"}],"discriminator":{"propertyName":"kind","mapping":{"condition":"#/components/schemas/ConditionInline","text":"#/components/schemas/TextInline","variable":"#/components/schemas/VariableInline"}}},"type":"array","maxItems":20,"minItems":1,"title":"Subject","description":"The subject value for this messagetemplaterevisioncreatein.","examples":[[{"kind":"text","text":"Example text"}]]},"body":{"items":{"oneOf":[{"$ref":"#/components/schemas/ParagraphBlock"},{"$ref":"#/components/schemas/BulletListBlock"},{"$ref":"#/components/schemas/OptOutNoticeBlock"}],"discriminator":{"propertyName":"kind","mapping":{"bullet_list":"#/components/schemas/BulletListBlock","opt_out_notice":"#/components/schemas/OptOutNoticeBlock","paragraph":"#/components/schemas/ParagraphBlock"}}},"type":"array","maxItems":20,"minItems":2,"title":"Body","description":"The body value for this messagetemplaterevisioncreatein.","examples":[[{"kind":"paragraph","content":[{"kind":"text","text":"Example text"}]},{"kind":"paragraph","content":[{"kind":"text","text":"Example text"}]}]]},"expected_previous_template_hash":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{64}$"},{"type":"null"}],"title":"Expected Previous Template Hash","description":"The expected previous template hash value for this messagetemplaterevisioncreatein.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"expected_policy_version":{"$ref":"#/components/schemas/MessageTemplatePolicyVersion","description":"The expected policy version value for this messagetemplaterevisioncreatein.","examples":["2026-07-13"]},"reason":{"type":"string","maxLength":500,"minLength":3,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"Reason","description":"The reason value for this messagetemplaterevisioncreatein.","examples":["Example value"]}},"additionalProperties":false,"type":"object","required":["template_key","revision_number","name","channel","purpose","language","variables","subject","body","expected_previous_template_hash","expected_policy_version","reason"],"title":"MessageTemplateRevisionCreateIn","description":"Create one immutable, structural outreach-message template revision.","examples":[{"body":[{"content":[{"kind":"text","text":"Kia ora."}],"kind":"paragraph"},{"kind":"opt_out_notice"}],"channel":"email","expected_policy_version":"2026-07-13","expected_previous_template_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","language":"en-nz","name":"First-touch introduction","purpose":"gtm_outreach","reason":"Publish a reviewed structural template for exact rendering.","revision_number":2,"subject":[{"kind":"text","text":"A practical idea for "},{"key":"contact.firstname","kind":"variable"}],"template_key":"first-touch","variables":[{"classification":"recipient_personal","key":"contact.firstname","max_length":50,"required":true}]}]},"MessageTemplateRevisionListOut":{"properties":{"schema_version":{"$ref":"#/components/schemas/MessageTemplateSchemaVersion","description":"The schema version value for this messagetemplaterevisionlistout.","examples":["2026-07-13"]},"availability":{"type":"string","const":"render_only","title":"Availability","description":"The availability value for this messagetemplaterevisionlistout."},"revisions":{"items":{"$ref":"#/components/schemas/MessageTemplateRevisionOut"},"type":"array","title":"Revisions","description":"The revisions value for this messagetemplaterevisionlistout.","examples":[[{"schema_version":"2026-07-13","status":"active","availability":"render_only","id":"msgtemplate_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"template_key":"example-key","revision_number":1,"name":"Example value","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","channel":"email","purpose":"gtm_outreach","language":"en-nz","variables":[{"key":"contact.firstname","classification":"recipient_personal","required":true,"max_length":1}],"subject":[{"kind":"text","text":"Example text"}],"body":[{"kind":"paragraph","content":[{"kind":"text","text":"Example text"}]},{"kind":"paragraph","content":[{"kind":"text","text":"Example text"}]}],"policy_version":"2026-07-13","template_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","previous_revision_id":"msgtemplate_aaaaaaaaaaaaaaaaaaaaaaaa","previous_template_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","arbitrary_template_code_accepted":false,"raw_html_accepted":false,"variable_values_stored":false,"attachment_uploads_accepted":false,"tracking_enabled":false,"provider_requests_made":0,"messages_enqueued":0,"messages_sent":0,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}]]},"total":{"type":"integer","maximum":5000.0,"minimum":0.0,"title":"Total","description":"The total value for this messagetemplaterevisionlistout.","examples":[0]},"limit":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Limit","description":"The limit value for this messagetemplaterevisionlistout.","examples":[1]},"offset":{"type":"integer","maximum":10000.0,"minimum":0.0,"title":"Offset","description":"The offset value for this messagetemplaterevisionlistout.","examples":[0]},"provider_requests_made":{"type":"integer","const":0,"title":"Provider Requests Made","description":"The provider requests made value for this messagetemplaterevisionlistout."},"messages_sent":{"type":"integer","const":0,"title":"Messages Sent","description":"The messages sent value for this messagetemplaterevisionlistout."},"outbound_authorized":{"type":"boolean","const":false,"title":"Outbound Authorized","description":"The outbound authorized value for this messagetemplaterevisionlistout."}},"additionalProperties":false,"type":"object","required":["schema_version","availability","revisions","total","limit","offset","provider_requests_made","messages_sent","outbound_authorized"],"title":"MessageTemplateRevisionListOut","description":"Structured messagetemplaterevisionlistout data exposed by the public API.","examples":[{"schema_version":"2026-07-13","availability":"render_only","revisions":[{"schema_version":"2026-07-13","status":"active","availability":"render_only","id":"msgtemplate_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"template_key":"example-key","revision_number":1,"name":"Example value","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","channel":"email","purpose":"gtm_outreach","language":"en-nz","variables":[{"key":"contact.firstname","classification":"recipient_personal","required":true,"max_length":1}],"subject":[{"kind":"text","text":"Example text"}],"body":[{"kind":"paragraph","content":[{"kind":"text","text":"Example text"}]},{"kind":"paragraph","content":[{"kind":"text","text":"Example text"}]}],"policy_version":"2026-07-13","template_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","previous_revision_id":"msgtemplate_aaaaaaaaaaaaaaaaaaaaaaaa","previous_template_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","arbitrary_template_code_accepted":false,"raw_html_accepted":false,"variable_values_stored":false,"attachment_uploads_accepted":false,"tracking_enabled":false,"provider_requests_made":0,"messages_enqueued":0,"messages_sent":0,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}],"total":0,"limit":1,"offset":0,"provider_requests_made":0,"messages_sent":0,"outbound_authorized":false}]},"MessageTemplateRevisionOut":{"properties":{"schema_version":{"$ref":"#/components/schemas/MessageTemplateSchemaVersion","description":"The schema version value for this messagetemplaterevisionout.","examples":["2026-07-13"]},"status":{"type":"string","const":"active","title":"Status","description":"The status value for this messagetemplaterevisionout."},"availability":{"type":"string","const":"render_only","title":"Availability","description":"The availability value for this messagetemplaterevisionout."},"id":{"type":"string","pattern":"^msgtemplate_[a-f0-9]{24}$","title":"Id","description":"The id value for this messagetemplaterevisionout.","examples":["msgtemplate_aaaaaaaaaaaaaaaaaaaaaaaa"]},"idempotent_replay":{"type":"boolean","title":"Idempotent Replay","description":"The idempotent replay value for this messagetemplaterevisionout.","examples":[true]},"template_key":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","title":"Template Key","description":"The template key value for this messagetemplaterevisionout.","examples":["example-key"]},"revision_number":{"type":"integer","maximum":1000.0,"minimum":1.0,"title":"Revision Number","description":"The revision number value for this messagetemplaterevisionout.","examples":[1]},"name":{"type":"string","maxLength":120,"minLength":1,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"Name","description":"The name value for this messagetemplaterevisionout.","examples":["Example value"]},"project_id":{"type":"string","pattern":"^proj_[a-f0-9]{24}$","title":"Project Id","description":"The project id value for this messagetemplaterevisionout.","examples":["proj_aaaaaaaaaaaaaaaaaaaaaaaa"]},"environment":{"type":"string","enum":["live","test"],"title":"Environment","description":"The environment value for this messagetemplaterevisionout.","examples":["live"]},"channel":{"type":"string","const":"email","title":"Channel","description":"The channel value for this messagetemplaterevisionout."},"purpose":{"type":"string","const":"gtm_outreach","title":"Purpose","description":"The purpose value for this messagetemplaterevisionout."},"language":{"type":"string","maxLength":24,"minLength":2,"pattern":"^[a-z]{2,3}(?:-[a-z0-9]{2,8}){0,2}$","title":"Language","description":"The language value for this messagetemplaterevisionout.","examples":["en-nz"]},"variables":{"items":{"$ref":"#/components/schemas/VariableDefinition"},"type":"array","maxItems":32,"title":"Variables","description":"The variables value for this messagetemplaterevisionout.","examples":[[{"key":"contact.firstname","classification":"recipient_personal","required":true,"max_length":1}]]},"subject":{"items":{"oneOf":[{"$ref":"#/components/schemas/TextInline"},{"$ref":"#/components/schemas/VariableInline"},{"$ref":"#/components/schemas/ConditionInline"}],"discriminator":{"propertyName":"kind","mapping":{"condition":"#/components/schemas/ConditionInline","text":"#/components/schemas/TextInline","variable":"#/components/schemas/VariableInline"}}},"type":"array","maxItems":20,"minItems":1,"title":"Subject","description":"The subject value for this messagetemplaterevisionout.","examples":[[{"kind":"text","text":"Example text"}]]},"body":{"items":{"oneOf":[{"$ref":"#/components/schemas/ParagraphBlock"},{"$ref":"#/components/schemas/BulletListBlock"},{"$ref":"#/components/schemas/OptOutNoticeBlock"}],"discriminator":{"propertyName":"kind","mapping":{"bullet_list":"#/components/schemas/BulletListBlock","opt_out_notice":"#/components/schemas/OptOutNoticeBlock","paragraph":"#/components/schemas/ParagraphBlock"}}},"type":"array","maxItems":20,"minItems":2,"title":"Body","description":"The body value for this messagetemplaterevisionout.","examples":[[{"kind":"paragraph","content":[{"kind":"text","text":"Example text"}]},{"kind":"paragraph","content":[{"kind":"text","text":"Example text"}]}]]},"policy_version":{"$ref":"#/components/schemas/MessageTemplatePolicyVersion","description":"The policy version value for this messagetemplaterevisionout.","examples":["2026-07-13"]},"template_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Template Hash","description":"The template hash value for this messagetemplaterevisionout.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"previous_revision_id":{"anyOf":[{"type":"string","pattern":"^msgtemplate_[a-f0-9]{24}$"},{"type":"null"}],"title":"Previous Revision Id","description":"The previous revision id value for this messagetemplaterevisionout.","examples":["msgtemplate_aaaaaaaaaaaaaaaaaaaaaaaa"]},"previous_template_hash":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{64}$"},{"type":"null"}],"title":"Previous Template Hash","description":"The previous template hash value for this messagetemplaterevisionout.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"reason":{"type":"string","maxLength":500,"minLength":3,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"Reason","description":"The reason value for this messagetemplaterevisionout.","examples":["Example value"]},"source":{"type":"string","enum":["manual","ai_generated"],"title":"Source","default":"manual","description":"The source value for this messagetemplaterevisionout."},"generation_config":{"anyOf":[{"$ref":"#/components/schemas/MessageTemplateGenerationConfigOut"},{"type":"null"}],"description":"The generation config value for this messagetemplaterevisionout.","examples":[{"operation":"template_generation","environment":"live","template_key":"example-key","name":"Example value","language":"en-nz","audience":"Example audience","objective":"Example objective","desired_next_step":"Example desired next step","options":{"tone":"direct","max_words":50,"max_links":0,"allowed_claims":["Example allowed claims"],"forbidden_claims":["Example forbidden claims"],"preferred_terms":["Example preferred terms"],"forbidden_terms":["Example forbidden terms"]}}]},"quality_score":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Quality Score","description":"The quality score value for this messagetemplaterevisionout.","examples":[0]},"generation_job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Generation Job Id","description":"The generation job id value for this messagetemplaterevisionout.","examples":["Example generation job id"]},"generation_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Generation Model","description":"The generation model value for this messagetemplaterevisionout.","examples":["Example generation model"]},"prompt_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt Version","description":"The prompt version value for this messagetemplaterevisionout.","examples":["Example prompt version"]},"generation_provider_requests":{"type":"integer","minimum":0.0,"title":"Generation Provider Requests","default":0,"description":"The generation provider requests value for this messagetemplaterevisionout."},"arbitrary_template_code_accepted":{"type":"boolean","const":false,"title":"Arbitrary Template Code Accepted","description":"The arbitrary template code accepted value for this messagetemplaterevisionout."},"raw_html_accepted":{"type":"boolean","const":false,"title":"Raw Html Accepted","description":"The raw html accepted value for this messagetemplaterevisionout."},"variable_values_stored":{"type":"boolean","const":false,"title":"Variable Values Stored","description":"The variable values stored value for this messagetemplaterevisionout."},"attachment_uploads_accepted":{"type":"boolean","const":false,"title":"Attachment Uploads Accepted","description":"The attachment uploads accepted value for this messagetemplaterevisionout."},"tracking_enabled":{"type":"boolean","const":false,"title":"Tracking Enabled","description":"The tracking enabled value for this messagetemplaterevisionout."},"provider_requests_made":{"type":"integer","const":0,"title":"Provider Requests Made","description":"The provider requests made value for this messagetemplaterevisionout."},"messages_enqueued":{"type":"integer","const":0,"title":"Messages Enqueued","description":"The messages enqueued value for this messagetemplaterevisionout."},"messages_sent":{"type":"integer","const":0,"title":"Messages Sent","description":"The messages sent value for this messagetemplaterevisionout."},"outbound_authorized":{"type":"boolean","const":false,"title":"Outbound Authorized","description":"The outbound authorized value for this messagetemplaterevisionout."},"crm_mutation_authorized":{"type":"boolean","const":false,"title":"Crm Mutation Authorized","description":"The crm mutation authorized value for this messagetemplaterevisionout."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"The created at value for this messagetemplaterevisionout.","examples":["2026-07-16T00:00:00Z"]}},"additionalProperties":false,"type":"object","required":["schema_version","status","availability","id","idempotent_replay","template_key","revision_number","name","project_id","environment","channel","purpose","language","variables","subject","body","policy_version","template_hash","previous_revision_id","previous_template_hash","reason","arbitrary_template_code_accepted","raw_html_accepted","variable_values_stored","attachment_uploads_accepted","tracking_enabled","provider_requests_made","messages_enqueued","messages_sent","outbound_authorized","crm_mutation_authorized","created_at"],"title":"MessageTemplateRevisionOut","description":"Structured messagetemplaterevisionout data exposed by the public API.","examples":[{"schema_version":"2026-07-13","status":"active","availability":"render_only","id":"msgtemplate_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"template_key":"example-key","revision_number":1,"name":"Example value","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","channel":"email","purpose":"gtm_outreach","language":"en-nz","variables":[{"key":"contact.firstname","classification":"recipient_personal","required":true,"max_length":1}],"subject":[{"kind":"text","text":"Example text"}],"body":[{"kind":"paragraph","content":[{"kind":"text","text":"Example text"}]},{"kind":"paragraph","content":[{"kind":"text","text":"Example text"}]}],"policy_version":"2026-07-13","template_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","previous_revision_id":"msgtemplate_aaaaaaaaaaaaaaaaaaaaaaaa","previous_template_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","arbitrary_template_code_accepted":false,"raw_html_accepted":false,"variable_values_stored":false,"attachment_uploads_accepted":false,"tracking_enabled":false,"provider_requests_made":0,"messages_enqueued":0,"messages_sent":0,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}]},"MessageTemplateSchemaVersion":{"type":"string","enum":["2026-07-13"],"title":"MessageTemplateSchemaVersion","description":"Readable historical response schemas; append versions, never replace them.","examples":["2026-07-13"]},"MessagingPillar":{"properties":{"name":{"type":"string","maxLength":160,"title":"Name","description":"The name value for this messagingpillar.","examples":["Example name"]},"message":{"type":"string","maxLength":1200,"title":"Message","description":"The message value for this messagingpillar.","examples":["Example message"]},"supporting_points":{"items":{"type":"string"},"type":"array","maxItems":12,"title":"Supporting Points","description":"The supporting points value for this messagingpillar.","examples":[["Example supporting points"]]},"proof_points":{"items":{"type":"string"},"type":"array","maxItems":12,"title":"Proof Points","description":"The proof points value for this messagingpillar.","examples":[["Example proof points"]]}},"additionalProperties":false,"type":"object","required":["name","message"],"title":"MessagingPillar","description":"Structured messagingpillar data exposed by the public API.","examples":[{"name":"Example name","message":"Example message"}]},"OfferOut":{"properties":{"id":{"type":"string","title":"Id","description":"The id value for this offerout.","examples":["Example id"]},"org_id":{"type":"string","title":"Org Id","description":"The org id value for this offerout.","examples":["Example org id"]},"brand_profile_id":{"type":"string","title":"Brand Profile Id","description":"The brand profile id value for this offerout.","examples":["Example brand profile id"]},"name":{"type":"string","title":"Name","description":"The name value for this offerout.","examples":["Example name"]},"key":{"type":"string","title":"Key","description":"The key value for this offerout.","examples":["Example key"]},"description":{"type":"string","title":"Description","description":"The description value for this offerout.","examples":["Example description"]},"value_props":{"items":{"type":"string"},"type":"array","title":"Value Props","description":"The value props value for this offerout.","examples":[["Example value props"]]},"proof_points":{"items":{"type":"string"},"type":"array","title":"Proof Points","description":"The proof points value for this offerout.","examples":[["Example proof points"]]},"pricing_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pricing Model","description":"The pricing model value for this offerout.","examples":["Example pricing model"]},"icp":{"additionalProperties":true,"type":"object","title":"Icp","description":"The icp value for this offerout.","examples":[{}]},"stage_fit":{"items":{"type":"string"},"type":"array","title":"Stage Fit","description":"The stage fit value for this offerout.","examples":[["Example stage fit"]]},"status":{"type":"string","title":"Status","description":"The status value for this offerout.","examples":["Example status"]},"archived":{"type":"boolean","title":"Archived","description":"The archived value for this offerout.","examples":[true]},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At","description":"The created at value for this offerout.","examples":["Example created at"]},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At","description":"The updated at value for this offerout.","examples":["Example updated at"]}},"type":"object","required":["id","org_id","brand_profile_id","name","key","description","value_props","proof_points","pricing_model","icp","stage_fit","status","archived","created_at","updated_at"],"title":"OfferOut","description":"Public representation of one organization Offer.","examples":[{"id":"Example id","org_id":"Example org id","brand_profile_id":"Example brand profile id","name":"Example name","key":"Example key","description":"Example description","value_props":["Example value props"],"proof_points":["Example proof points"],"pricing_model":"Example pricing model","icp":{},"stage_fit":["Example stage fit"],"status":"Example status","archived":true,"created_at":"Example created at","updated_at":"Example updated at"}]},"OffersResponse":{"properties":{"offers":{"items":{"$ref":"#/components/schemas/OfferOut"},"type":"array","title":"Offers","description":"The offers value for this offersresponse.","examples":[[{"id":"Example id","org_id":"Example org id","brand_profile_id":"Example brand profile id","name":"Example name","key":"Example key","description":"Example description","value_props":["Example value props"],"proof_points":["Example proof points"],"pricing_model":"Example pricing model","icp":{},"stage_fit":["Example stage fit"],"status":"Example status","archived":true,"created_at":"Example created at","updated_at":"Example updated at"}]]}},"type":"object","required":["offers"],"title":"OffersResponse","description":"Organization-scoped Offer catalog response.","examples":[{"offers":[{"id":"Example id","org_id":"Example org id","brand_profile_id":"Example brand profile id","name":"Example name","key":"Example key","description":"Example description","value_props":["Example value props"],"proof_points":["Example proof points"],"pricing_model":"Example pricing model","icp":{},"stage_fit":["Example stage fit"],"status":"Example status","archived":true,"created_at":"Example created at","updated_at":"Example updated at"}]}]},"OptOutNoticeBlock":{"properties":{"kind":{"type":"string","const":"opt_out_notice","title":"Kind","description":"The kind value for this optoutnoticeblock."}},"additionalProperties":false,"type":"object","required":["kind"],"title":"OptOutNoticeBlock","description":"Structured optoutnoticeblock data exposed by the public API.","examples":[{"kind":"opt_out_notice"}]},"OutcomeCreateIn":{"properties":{"source":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z][a-z0-9._-]*$","title":"Source","description":"The source value for this outcomecreatein.","examples":["example_key"]},"external_event_id":{"type":"string","maxLength":240,"minLength":1,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"External Event Id","description":"The external event id value for this outcomecreatein.","examples":["Example value"]},"type":{"type":"string","enum":["qualification_approved","qualification_rejected","draft_approved","draft_rejected","delivered","positive_reply","negative_reply","meeting_booked","sales_qualified","opportunity_created","closed_won","closed_lost","ghosted","bounced","unsubscribed","email_not_found","provider_failed"],"title":"Type","description":"The type value for this outcomecreatein.","examples":["qualification_approved"]},"occurred_at":{"type":"string","format":"date-time","title":"Occurred At","description":"The occurred at value for this outcomecreatein.","examples":["2026-07-16T00:00:00Z"]},"prospecting_job_id":{"anyOf":[{"type":"string","pattern":"^job_[a-f0-9]{24}$"},{"type":"null"}],"title":"Prospecting Job Id","description":"The prospecting job id value for this outcomecreatein.","examples":["job_aaaaaaaaaaaaaaaaaaaaaaaa"]},"prospect_id":{"anyOf":[{"type":"string","maxLength":120,"minLength":1,"pattern":"^[^\\x00-\\x1f\\x7f]+$"},{"type":"null"}],"title":"Prospect Id","description":"The prospect id value for this outcomecreatein.","examples":["Example value"]},"account_domain":{"anyOf":[{"type":"string","maxLength":253},{"type":"null"}],"title":"Account Domain","description":"The account domain value for this outcomecreatein.","examples":["Example account domain"]},"campaign_id":{"anyOf":[{"type":"string","pattern":"^camp_[a-f0-9]{24}$"},{"type":"null"}],"title":"Campaign Id","description":"The campaign id value for this outcomecreatein.","examples":["camp_aaaaaaaaaaaaaaaaaaaaaaaa"]},"offer_id":{"anyOf":[{"type":"string","pattern":"^offer_[a-f0-9]{24}$"},{"type":"null"}],"title":"Offer Id","description":"The offer id value for this outcomecreatein.","examples":["offer_aaaaaaaaaaaaaaaaaaaaaaaa"]},"brand_profile_id":{"anyOf":[{"type":"string","pattern":"^brand_[a-f0-9]{24}$"},{"type":"null"}],"title":"Brand Profile Id","description":"The brand profile id value for this outcomecreatein.","examples":["brand_aaaaaaaaaaaaaaaaaaaaaaaa"]},"audience_id":{"anyOf":[{"type":"string","pattern":"^audience_[a-f0-9]{24}$"},{"type":"null"}],"title":"Audience Id","description":"The audience id value for this outcomecreatein.","examples":["audience_aaaaaaaaaaaaaaaaaaaaaaaa"]},"playbook_job_id":{"anyOf":[{"type":"string","pattern":"^job_[a-f0-9]{24}$"},{"type":"null"}],"title":"Playbook Job Id","description":"The playbook job id value for this outcomecreatein.","examples":["job_aaaaaaaaaaaaaaaaaaaaaaaa"]},"message_template_revision_id":{"anyOf":[{"type":"string","pattern":"^msgtpl_[a-f0-9]{24}$"},{"type":"null"}],"title":"Message Template Revision Id","description":"The message template revision id value for this outcomecreatein.","examples":["msgtpl_aaaaaaaaaaaaaaaaaaaaaaaa"]},"channel":{"anyOf":[{"type":"string","enum":["email","linkedin","sms","voice","other"]},{"type":"null"}],"title":"Channel","description":"The channel value for this outcomecreatein.","examples":["email"]},"reason_code":{"anyOf":[{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z][a-z0-9._-]*$"},{"type":"null"}],"title":"Reason Code","description":"The reason code value for this outcomecreatein.","examples":["example_key"]},"connector_id":{"anyOf":[{"type":"string","pattern":"^conn_[a-f0-9]{24}$"},{"type":"null"}],"title":"Connector Id","description":"The connector id value for this outcomecreatein.","examples":["conn_aaaaaaaaaaaaaaaaaaaaaaaa"]},"external_record_id":{"anyOf":[{"type":"string","maxLength":240,"minLength":1,"pattern":"^[^\\x00-\\x1f\\x7f]+$"},{"type":"null"}],"title":"External Record Id","description":"The external record id value for this outcomecreatein.","examples":["Example value"]},"amount_usd_cents":{"anyOf":[{"type":"integer","maximum":100000000000.0,"minimum":0.0},{"type":"null"}],"title":"Amount Usd Cents","description":"The amount usd cents value for this outcomecreatein.","examples":[0]}},"additionalProperties":false,"type":"object","required":["source","external_event_id","type","occurred_at"],"title":"OutcomeCreateIn","description":"Append-only feedback about a prospect, an account, or a campaign.","examples":[{"source":"example_key","external_event_id":"Example value","type":"qualification_approved","occurred_at":"2026-07-16T00:00:00Z"}]},"OutcomeInsightGroup":{"properties":{"group":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Group","description":"The group value for this outcomeinsightgroup.","examples":["Example group"]},"total":{"type":"integer","title":"Total","description":"The total value for this outcomeinsightgroup.","examples":[0]},"learning_candidates":{"type":"integer","title":"Learning Candidates","description":"The learning candidates value for this outcomeinsightgroup.","examples":[0]},"by_classification":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Classification","description":"The by classification value for this outcomeinsightgroup.","examples":[{}]},"by_type":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Type","description":"The by type value for this outcomeinsightgroup.","examples":[{}]},"positive_replies":{"type":"integer","title":"Positive Replies","description":"The positive replies value for this outcomeinsightgroup.","examples":[0]},"meetings_booked":{"type":"integer","title":"Meetings Booked","description":"The meetings booked value for this outcomeinsightgroup.","examples":[0]},"opportunities":{"type":"integer","title":"Opportunities","description":"The opportunities value for this outcomeinsightgroup.","examples":[0]},"wins":{"type":"integer","title":"Wins","description":"The wins value for this outcomeinsightgroup.","examples":[0]},"losses":{"type":"integer","title":"Losses","description":"The losses value for this outcomeinsightgroup.","examples":[0]},"win_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Win Rate","description":"The win rate value for this outcomeinsightgroup.","examples":[0.0]},"revenue_usd_cents":{"type":"integer","title":"Revenue Usd Cents","description":"The revenue usd cents value for this outcomeinsightgroup.","examples":[0]}},"type":"object","required":["group","total","learning_candidates","by_classification","by_type","positive_replies","meetings_booked","opportunities","wins","losses","win_rate","revenue_usd_cents"],"title":"OutcomeInsightGroup","description":"Structured outcomeinsightgroup data exposed by the public API.","examples":[{"group":"Example group","total":0,"learning_candidates":0,"by_classification":{},"by_type":{},"positive_replies":0,"meetings_booked":0,"opportunities":0,"wins":0,"losses":0,"win_rate":0.0,"revenue_usd_cents":0}]},"OutcomeInsightsResponse":{"properties":{"group_by":{"type":"string","enum":["campaign","offer","brand_profile","audience","playbook_job","message_template_revision","type","channel","account_domain"],"title":"Group By","description":"The group by value for this outcomeinsightsresponse.","examples":["campaign"]},"since":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Since","description":"The since value for this outcomeinsightsresponse.","examples":["2026-07-16T00:00:00Z"]},"until":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Until","description":"The until value for this outcomeinsightsresponse.","examples":["2026-07-16T00:00:00Z"]},"total_outcomes":{"type":"integer","title":"Total Outcomes","description":"The total outcomes value for this outcomeinsightsresponse.","examples":[0]},"total_groups":{"type":"integer","title":"Total Groups","description":"The total groups value for this outcomeinsightsresponse.","examples":[0]},"groups":{"items":{"$ref":"#/components/schemas/OutcomeInsightGroup"},"type":"array","title":"Groups","description":"The groups value for this outcomeinsightsresponse.","examples":[[{"group":"Example group","total":0,"learning_candidates":0,"by_classification":{},"by_type":{},"positive_replies":0,"meetings_booked":0,"opportunities":0,"wins":0,"losses":0,"win_rate":0.0,"revenue_usd_cents":0}]]}},"type":"object","required":["group_by","since","until","total_outcomes","total_groups","groups"],"title":"OutcomeInsightsResponse","description":"Structured outcomeinsightsresponse data exposed by the public API.","examples":[{"group_by":"campaign","since":"2026-07-16T00:00:00Z","until":"2026-07-16T00:00:00Z","total_outcomes":0,"total_groups":0,"groups":[{"group":"Example group","total":0,"learning_candidates":0,"by_classification":{},"by_type":{},"positive_replies":0,"meetings_booked":0,"opportunities":0,"wins":0,"losses":0,"win_rate":0.0,"revenue_usd_cents":0}]}]},"OutcomeOut":{"properties":{"id":{"type":"string","title":"Id","description":"The id value for this outcomeout.","examples":["Example id"]},"status":{"type":"string","const":"recorded","title":"Status","description":"The status value for this outcomeout."},"idempotent_replay":{"type":"boolean","title":"Idempotent Replay","description":"The idempotent replay value for this outcomeout.","examples":[true]},"project_id":{"type":"string","title":"Project Id","description":"The project id value for this outcomeout.","examples":["Example project id"]},"environment":{"type":"string","enum":["live","test"],"title":"Environment","description":"The environment value for this outcomeout.","examples":["live"]},"subject_kind":{"type":"string","enum":["prospect","account","campaign"],"title":"Subject Kind","description":"The subject kind value for this outcomeout.","examples":["prospect"]},"prospecting_job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prospecting Job Id","description":"The prospecting job id value for this outcomeout.","examples":["Example prospecting job id"]},"prospect_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prospect Id","description":"The prospect id value for this outcomeout.","examples":["Example prospect id"]},"account_domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Domain","description":"The account domain value for this outcomeout.","examples":["Example account domain"]},"campaign_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Campaign Id","description":"The campaign id value for this outcomeout.","examples":["Example campaign id"]},"offer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Offer Id","description":"The offer id value for this outcomeout.","examples":["Example offer id"]},"brand_profile_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand Profile Id","description":"The brand profile id value for this outcomeout.","examples":["Example brand profile id"]},"audience_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Audience Id","description":"The audience id value for this outcomeout.","examples":["Example audience id"]},"playbook_job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Playbook Job Id","description":"The playbook job id value for this outcomeout.","examples":["Example playbook job id"]},"message_template_revision_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message Template Revision Id","description":"The message template revision id value for this outcomeout.","examples":["Example message template revision id"]},"connector_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Connector Id","description":"The connector id value for this outcomeout.","examples":["Example connector id"]},"source":{"type":"string","title":"Source","description":"The source value for this outcomeout.","examples":["Example source"]},"external_event_id":{"type":"string","title":"External Event Id","description":"The external event id value for this outcomeout.","examples":["Example external event id"]},"external_record_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Record Id","description":"The external record id value for this outcomeout.","examples":["Example external record id"]},"type":{"type":"string","enum":["qualification_approved","qualification_rejected","draft_approved","draft_rejected","delivered","positive_reply","negative_reply","meeting_booked","sales_qualified","opportunity_created","closed_won","closed_lost","ghosted","bounced","unsubscribed","email_not_found","provider_failed"],"title":"Type","description":"The type value for this outcomeout.","examples":["qualification_approved"]},"classification":{"type":"string","enum":["preference","commercial","operational"],"title":"Classification","description":"The classification value for this outcomeout.","examples":["preference"]},"learning_candidate":{"type":"boolean","title":"Learning Candidate","description":"The learning candidate value for this outcomeout.","examples":[true]},"verification_status":{"type":"string","const":"unverified","title":"Verification Status","description":"The verification status value for this outcomeout."},"eligible_for_learning":{"type":"boolean","title":"Eligible For Learning","description":"The eligible for learning value for this outcomeout.","examples":[true]},"channel":{"anyOf":[{"type":"string","enum":["email","linkedin","sms","voice","other"]},{"type":"null"}],"title":"Channel","description":"The channel value for this outcomeout.","examples":["email"]},"reason_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason Code","description":"The reason code value for this outcomeout.","examples":["Example reason code"]},"amount_usd_cents":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Amount Usd Cents","description":"The amount usd cents value for this outcomeout.","examples":[0]},"occurred_at":{"type":"string","format":"date-time","title":"Occurred At","description":"The occurred at value for this outcomeout.","examples":["2026-07-16T00:00:00Z"]},"prospecting_result_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prospecting Result Hash","description":"The prospecting result hash value for this outcomeout.","examples":["Example prospecting result hash"]},"recorded_at":{"type":"string","format":"date-time","title":"Recorded At","description":"The recorded at value for this outcomeout.","examples":["2026-07-16T00:00:00Z"]}},"type":"object","required":["id","status","idempotent_replay","project_id","environment","subject_kind","prospecting_job_id","prospect_id","account_domain","campaign_id","offer_id","brand_profile_id","audience_id","playbook_job_id","message_template_revision_id","connector_id","source","external_event_id","external_record_id","type","classification","learning_candidate","verification_status","eligible_for_learning","channel","reason_code","amount_usd_cents","occurred_at","prospecting_result_hash","recorded_at"],"title":"OutcomeOut","description":"Structured outcomeout data exposed by the public API.","examples":[{"id":"Example id","status":"recorded","idempotent_replay":true,"project_id":"Example project id","environment":"live","subject_kind":"prospect","prospecting_job_id":"Example prospecting job id","prospect_id":"Example prospect id","account_domain":"Example account domain","campaign_id":"Example campaign id","offer_id":"Example offer id","brand_profile_id":"Example brand profile id","audience_id":"Example audience id","playbook_job_id":"Example playbook job id","message_template_revision_id":"Example message template revision id","connector_id":"Example connector id","source":"Example source","external_event_id":"Example external event id","external_record_id":"Example external record id","type":"qualification_approved","classification":"preference","learning_candidate":true,"verification_status":"unverified","eligible_for_learning":true,"channel":"email","reason_code":"Example reason code","amount_usd_cents":0,"occurred_at":"2026-07-16T00:00:00Z","prospecting_result_hash":"Example prospecting result hash","recorded_at":"2026-07-16T00:00:00Z"}]},"OutcomesResponse":{"properties":{"outcomes":{"items":{"$ref":"#/components/schemas/OutcomeOut"},"type":"array","title":"Outcomes","description":"The outcomes value for this outcomesresponse.","examples":[[{"id":"Example id","status":"recorded","idempotent_replay":true,"project_id":"Example project id","environment":"live","subject_kind":"prospect","prospecting_job_id":"Example prospecting job id","prospect_id":"Example prospect id","account_domain":"Example account domain","campaign_id":"Example campaign id","offer_id":"Example offer id","brand_profile_id":"Example brand profile id","audience_id":"Example audience id","playbook_job_id":"Example playbook job id","message_template_revision_id":"Example message template revision id","connector_id":"Example connector id","source":"Example source","external_event_id":"Example external event id","external_record_id":"Example external record id","type":"qualification_approved","classification":"preference","learning_candidate":true,"verification_status":"unverified","eligible_for_learning":true,"channel":"email","reason_code":"Example reason code","amount_usd_cents":0,"occurred_at":"2026-07-16T00:00:00Z","prospecting_result_hash":"Example prospecting result hash","recorded_at":"2026-07-16T00:00:00Z"}]]},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"The next cursor value for this outcomesresponse.","examples":["Example next cursor"]},"total":{"type":"integer","title":"Total","description":"The total value for this outcomesresponse.","examples":[0]}},"type":"object","required":["outcomes","next_cursor","total"],"title":"OutcomesResponse","description":"Structured outcomesresponse data exposed by the public API.","examples":[{"outcomes":[{"id":"Example id","status":"recorded","idempotent_replay":true,"project_id":"Example project id","environment":"live","subject_kind":"prospect","prospecting_job_id":"Example prospecting job id","prospect_id":"Example prospect id","account_domain":"Example account domain","campaign_id":"Example campaign id","offer_id":"Example offer id","brand_profile_id":"Example brand profile id","audience_id":"Example audience id","playbook_job_id":"Example playbook job id","message_template_revision_id":"Example message template revision id","connector_id":"Example connector id","source":"Example source","external_event_id":"Example external event id","external_record_id":"Example external record id","type":"qualification_approved","classification":"preference","learning_candidate":true,"verification_status":"unverified","eligible_for_learning":true,"channel":"email","reason_code":"Example reason code","amount_usd_cents":0,"occurred_at":"2026-07-16T00:00:00Z","prospecting_result_hash":"Example prospecting result hash","recorded_at":"2026-07-16T00:00:00Z"}],"next_cursor":"Example next cursor","total":0}]},"OutreachDraft":{"properties":{"subject":{"type":"string","maxLength":500,"title":"Subject","description":"The subject value for this outreachdraft.","examples":["Example subject"]},"body":{"type":"string","maxLength":8000,"title":"Body","description":"The body value for this outreachdraft.","examples":["Example body"]},"follow_up_after_hours":{"anyOf":[{"type":"integer","maximum":720.0,"minimum":1.0},{"type":"null"}],"title":"Follow Up After Hours","description":"The follow up after hours value for this outreachdraft.","examples":[1]}},"type":"object","required":["subject","body"],"title":"OutreachDraft","description":"Structured outreachdraft data exposed by the public API.","examples":[{"subject":"Example subject","body":"Example body"}]},"ParagraphBlock":{"properties":{"kind":{"type":"string","const":"paragraph","title":"Kind","description":"The kind value for this paragraphblock."},"content":{"items":{"oneOf":[{"$ref":"#/components/schemas/TextInline"},{"$ref":"#/components/schemas/VariableInline"},{"$ref":"#/components/schemas/ConditionInline"}],"discriminator":{"propertyName":"kind","mapping":{"condition":"#/components/schemas/ConditionInline","text":"#/components/schemas/TextInline","variable":"#/components/schemas/VariableInline"}}},"type":"array","maxItems":50,"minItems":1,"title":"Content","description":"The content value for this paragraphblock.","examples":[[{"kind":"text","text":"Example text"}]]}},"additionalProperties":false,"type":"object","required":["kind","content"],"title":"ParagraphBlock","description":"Structured paragraphblock data exposed by the public API.","examples":[{"kind":"paragraph","content":[{"kind":"text","text":"Example text"}]}]},"PersonalityTrait":{"properties":{"name":{"type":"string","maxLength":100,"title":"Name","description":"The name value for this personalitytrait.","examples":["Example name"]},"description":{"type":"string","maxLength":500,"title":"Description","description":"The description value for this personalitytrait.","examples":["Example description"]},"we_are":{"type":"string","maxLength":300,"title":"We Are","description":"The we are value for this personalitytrait.","examples":["Example we are"]},"we_are_not":{"type":"string","maxLength":300,"title":"We Are Not","description":"The we are not value for this personalitytrait.","examples":["Example we are not"]}},"additionalProperties":false,"type":"object","required":["name","description","we_are","we_are_not"],"title":"PersonalityTrait","description":"Structured personalitytrait data exposed by the public API.","examples":[{"name":"Example name","description":"Example description","we_are":"Example we are","we_are_not":"Example we are not"}]},"PlaybookInput":{"anyOf":[{"properties":{"target_company":{"type":"string","minLength":1,"description":"A non-empty target company name satisfies the Playbooks target requirement.","examples":["Acme Corporation"]}},"required":["target_company"]},{"properties":{"target_company_domain":{"type":"string","minLength":1,"description":"A non-empty target company domain satisfies the Playbooks target requirement.","examples":["acme.example"]}},"required":["target_company_domain"]}],"properties":{"target_company":{"anyOf":[{"type":"string","maxLength":160,"minLength":1},{"type":"null"}],"title":"Target Company","description":"Target company name. Provide this, `target_company_domain`, or both.","examples":["Acme Corporation"]},"target_company_domain":{"anyOf":[{"type":"string","maxLength":253,"minLength":3,"pattern":"^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"},{"type":"null"}],"format":"hostname","title":"Target Company Domain","description":"Target company domain without a path, for example `acme.example`.","examples":["acme.example"]},"anchor_company":{"anyOf":[{"type":"string","maxLength":160,"minLength":1},{"type":"null"}],"title":"Anchor Company","description":"Seller or anchor company the playbook represents. Defaults to the selected brand profile.","examples":["Northstar Analytics"]},"product_info":{"anyOf":[{"type":"string","maxLength":12000,"minLength":1},{"type":"null"}],"title":"Product Info","description":"Optional product context used to tailor the playbook.","examples":["Revenue-intelligence software for enterprise sales teams."]},"tone":{"type":"string","enum":["consultative","direct","technical"],"title":"Tone","description":"Writing tone: `consultative`, `direct`, or `technical`.","default":"consultative","examples":["consultative"]},"sections":{"anyOf":[{"items":{"type":"string","enum":["summary","objective","value_props","sales_angles","personas","services","tech_stack","integrations","objections","meeting_note"]},"type":"array","maxItems":10,"minItems":1},{"type":"null"}],"title":"Sections","description":"Optional subset of sections to generate. Omit to generate the complete playbook.","examples":[["summary","value_props","personas"]]},"model":{"type":"string","enum":["default"],"const":"default","title":"Model","description":"Generation model selection. `default` is the currently supported model.","default":"default","examples":["default"]},"intelligence":{"anyOf":[{"type":"string","enum":["low","medium","high","ultra"]},{"type":"null"}],"title":"Intelligence","description":"Optional model tier for the generation agents: `low`, `medium`, `high`, or `ultra`. Defaults from the selected playbook template, else `high`.","examples":["high"]},"brand_profile_id":{"anyOf":[{"type":"string","maxLength":80,"minLength":1},{"type":"null"}],"title":"Brand Profile Id","description":"Optional organization brand-profile identifier. It must belong to the API key's organization.","examples":["brand_01h8z3m2q7"]},"brand_profile_key":{"anyOf":[{"type":"string","maxLength":80,"minLength":1},{"type":"null"}],"title":"Brand Profile Key","description":"Optional stable brand-profile key. It must agree with `brand_profile_id` when both are supplied.","examples":["northstar"]},"stage":{"anyOf":[{"type":"string","maxLength":40,"minLength":1},{"type":"null"}],"title":"Stage","description":"Optional deal stage the playbook targets. Any short lowercase slug is accepted — organizations define their own stage vocabulary on their playbook templates; `GET /v1/playbook-templates` lists the catalog's suggested stages alongside org-defined ones. Defaults from `playbook_template_key` when omitted.","examples":["discovery","renewal","expansion_qbr"]},"playbook_template_key":{"anyOf":[{"type":"string","maxLength":80,"minLength":1},{"type":"null"}],"title":"Playbook Template Key","description":"Optional playbook template key from `GET /v1/playbook-templates` — an organization-defined template (fixing offer, brand, stage and sales approach) or a curated catalog entry. Unknown keys fail the request with `playbook_template_not_found`. A catalog key must agree with `stage` when both are supplied.","examples":["discovery_deep_dive"]},"offer_id":{"anyOf":[{"type":"string","maxLength":80,"minLength":1},{"type":"null"}],"title":"Offer Id","description":"Optional offer to sell with; its value propositions and proof points are embedded as generation context.","examples":["offer_0f47ac10b58cc4372a5670e0"]},"campaign_id":{"anyOf":[{"type":"string","maxLength":80,"minLength":1},{"type":"null"}],"title":"Campaign Id","description":"Optional campaign frame for the playbook. The campaign's offer is inherited when `offer_id` is omitted.","examples":["camp_0f47ac10b58cc4372a5670e0"]}},"additionalProperties":false,"type":"object","title":"PlaybookInput","description":"Stable public input shape for Playbooks.\n\nThe backend still calls this value `target_company_domain`; the platform keeps the\npublic API broader so a caller can provide either a name or a domain.","examples":[{"anchor_company":"Northstar Analytics","model":"default","product_info":"Revenue-intelligence software for enterprise sales teams.","sections":["summary","value_props","personas","objections"],"target_company_domain":"acme.example","tone":"consultative"}]},"ProfessionalNetworkConnectionBindingOut":{"properties":{"connection_id":{"type":"string","pattern":"^conn_[a-f0-9]{24}$","title":"Connection Id","description":"The connection id value for this professionalnetworkconnectionbindingout.","examples":["conn_aaaaaaaaaaaaaaaaaaaaaaaa"]},"provider_key":{"type":"string","const":"linkedin-sales-navigator","title":"Provider Key","description":"The provider key value for this professionalnetworkconnectionbindingout."},"manifest_version":{"type":"string","const":"2026-07-14","title":"Manifest Version","description":"The manifest version value for this professionalnetworkconnectionbindingout."},"credentials_version":{"type":"integer","maximum":1000000.0,"minimum":1.0,"title":"Credentials Version","description":"The credentials version value for this professionalnetworkconnectionbindingout.","examples":[1]},"configured_fields":{"items":{"type":"string"},"type":"array","maxItems":4,"minItems":4,"title":"Configured Fields","description":"The configured fields value for this professionalnetworkconnectionbindingout.","examples":[["Example configured fields","Example configured fields","Example configured fields","Example configured fields"]]},"status":{"type":"string","const":"configured","title":"Status","description":"The status value for this professionalnetworkconnectionbindingout."},"live_verification_status":{"type":"string","const":"not_run","title":"Live Verification Status","description":"The live verification status value for this professionalnetworkconnectionbindingout."},"credentials_decrypted":{"type":"boolean","const":false,"title":"Credentials Decrypted","description":"The credentials decrypted value for this professionalnetworkconnectionbindingout."},"access_token_stored":{"type":"boolean","const":false,"title":"Access Token Stored","description":"The access token stored value for this professionalnetworkconnectionbindingout."},"member_password_stored":{"type":"boolean","const":false,"title":"Member Password Stored","description":"The member password stored value for this professionalnetworkconnectionbindingout."},"browser_session_stored":{"type":"boolean","const":false,"title":"Browser Session Stored","description":"The browser session stored value for this professionalnetworkconnectionbindingout."}},"additionalProperties":false,"type":"object","required":["connection_id","provider_key","manifest_version","credentials_version","configured_fields","status","live_verification_status","credentials_decrypted","access_token_stored","member_password_stored","browser_session_stored"],"title":"ProfessionalNetworkConnectionBindingOut","description":"Structured professionalnetworkconnectionbindingout data exposed by the public API.","examples":[{"connection_id":"conn_aaaaaaaaaaaaaaaaaaaaaaaa","provider_key":"linkedin-sales-navigator","manifest_version":"2026-07-14","credentials_version":1,"configured_fields":["Example configured fields","Example configured fields","Example configured fields","Example configured fields"],"status":"configured","live_verification_status":"not_run","credentials_decrypted":false,"access_token_stored":false,"member_password_stored":false,"browser_session_stored":false}]},"ProfessionalNetworkConnectionIn":{"properties":{"connection_id":{"type":"string","pattern":"^conn_[a-f0-9]{24}$","title":"Connection Id","description":"The connection id value for this professionalnetworkconnectionin.","examples":["conn_aaaaaaaaaaaaaaaaaaaaaaaa"]},"expected_manifest_version":{"type":"string","const":"2026-07-14","title":"Expected Manifest Version","description":"The expected manifest version value for this professionalnetworkconnectionin."},"expected_credentials_version":{"type":"integer","maximum":1000000.0,"minimum":1.0,"title":"Expected Credentials Version","description":"The expected credentials version value for this professionalnetworkconnectionin.","examples":[1]}},"additionalProperties":false,"type":"object","required":["connection_id","expected_manifest_version","expected_credentials_version"],"title":"ProfessionalNetworkConnectionIn","description":"Bind safe connection metadata; credentials and tokens never enter this contract.","examples":[{"connection_id":"conn_aaaaaaaaaaaaaaaaaaaaaaaa","expected_manifest_version":"2026-07-14","expected_credentials_version":1}]},"ProfessionalNetworkDisplayComponent":{"type":"string","enum":["profile_summary","recent_activity","related_leads"],"title":"ProfessionalNetworkDisplayComponent","description":"Structured professionalnetworkdisplaycomponent data exposed by the public API.","examples":["profile_summary"]},"ProfessionalNetworkMemberBindingOut":{"properties":{"id":{"type":"string","pattern":"^audmem_[a-f0-9]{24}$","title":"Id","description":"The id value for this professionalnetworkmemberbindingout.","examples":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"]},"source_result_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Source Result Hash","description":"The source result hash value for this professionalnetworkmemberbindingout.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"review_status":{"type":"string","const":"included","title":"Review Status","description":"The review status value for this professionalnetworkmemberbindingout."},"snapshot_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Snapshot Hash","description":"The snapshot hash value for this professionalnetworkmemberbindingout.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"identity_reference_present":{"type":"boolean","const":true,"title":"Identity Reference Present","description":"The identity reference present value for this professionalnetworkmemberbindingout."}},"additionalProperties":false,"type":"object","required":["id","source_result_hash","review_status","snapshot_hash","identity_reference_present"],"title":"ProfessionalNetworkMemberBindingOut","description":"Structured professionalnetworkmemberbindingout data exposed by the public API.","examples":[{"id":"audmem_aaaaaaaaaaaaaaaaaaaaaaaa","source_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","review_status":"included","snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","identity_reference_present":true}]},"ProfessionalNetworkPolicyVersion":{"type":"string","enum":["2026-07-13","2026-07-15"],"title":"ProfessionalNetworkPolicyVersion","description":"Readable/replayable planning policies; append versions, never replace them.","examples":["2026-07-13"]},"ProfessionalNetworkPurpose":{"type":"string","enum":["crm_sync"],"title":"ProfessionalNetworkPurpose","description":"Structured professionalnetworkpurpose data exposed by the public API.","examples":["crm_sync"]},"ProfessionalNetworkSchemaVersion":{"type":"string","enum":["2026-07-13","2026-07-15"],"title":"ProfessionalNetworkSchemaVersion","description":"Readable historical response schemas; append versions, never replace them.","examples":["2026-07-13"]},"ProfessionalNetworkSelectionIn":{"properties":{"mode":{"$ref":"#/components/schemas/ProfessionalNetworkSelectionMode","description":"The mode value for this professionalnetworkselectionin.","examples":["included"]},"member_ids":{"items":{"type":"string","pattern":"^audmem_[a-f0-9]{24}$"},"type":"array","maxItems":25,"title":"Member Ids","description":"The member ids value for this professionalnetworkselectionin.","examples":[["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"]]}},"additionalProperties":false,"type":"object","required":["mode"],"title":"ProfessionalNetworkSelectionIn","description":"Select all reviewed members or one exact reviewed subset.","examples":[{"mode":"included"}]},"ProfessionalNetworkSelectionMode":{"type":"string","enum":["included","explicit"],"title":"ProfessionalNetworkSelectionMode","description":"Structured professionalnetworkselectionmode data exposed by the public API.","examples":["included"]},"ProfessionalNetworkSelectionOut":{"properties":{"mode":{"$ref":"#/components/schemas/ProfessionalNetworkSelectionMode","description":"The mode value for this professionalnetworkselectionout.","examples":["included"]},"member_ids":{"items":{"type":"string","pattern":"^audmem_[a-f0-9]{24}$"},"type":"array","maxItems":25,"minItems":1,"title":"Member Ids","description":"The member ids value for this professionalnetworkselectionout.","examples":[["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"]]},"member_count":{"type":"integer","maximum":25.0,"minimum":1.0,"title":"Member Count","description":"The member count value for this professionalnetworkselectionout.","examples":[1]},"member_snapshot_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Member Snapshot Hash","description":"The member snapshot hash value for this professionalnetworkselectionout.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"member_bindings":{"items":{"$ref":"#/components/schemas/ProfessionalNetworkMemberBindingOut"},"type":"array","maxItems":25,"minItems":1,"title":"Member Bindings","description":"The member bindings value for this professionalnetworkselectionout.","examples":[[{"id":"audmem_aaaaaaaaaaaaaaaaaaaaaaaa","source_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","review_status":"included","snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","identity_reference_present":true}]]}},"additionalProperties":false,"type":"object","required":["mode","member_ids","member_count","member_snapshot_hash","member_bindings"],"title":"ProfessionalNetworkSelectionOut","description":"Structured professionalnetworkselectionout data exposed by the public API.","examples":[{"mode":"included","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"member_count":1,"member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","member_bindings":[{"id":"audmem_aaaaaaaaaaaaaaaaaaaaaaaa","source_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","review_status":"included","snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","identity_reference_present":true}]}]},"ProfessionalNetworkSourcePolicyOut":{"properties":{"provider":{"type":"string","const":"linkedin_sales_navigator","title":"Provider","description":"The provider value for this professionalnetworksourcepolicyout."},"display_name":{"type":"string","const":"LinkedIn Sales Navigator","title":"Display Name","description":"The display name value for this professionalnetworksourcepolicyout."},"program":{"type":"string","const":"sales_navigator_application_platform","title":"Program","description":"The program value for this professionalnetworksourcepolicyout."},"operation":{"type":"string","const":"display_services","title":"Operation","description":"The operation value for this professionalnetworksourcepolicyout."},"integration_mode":{"type":"string","const":"official_api_oauth2","title":"Integration Mode","description":"The integration mode value for this professionalnetworksourcepolicyout."},"oauth_flow":{"type":"string","const":"member_authorization","title":"Oauth Flow","description":"The oauth flow value for this professionalnetworksourcepolicyout."},"required_scopes":{"items":{"type":"string","const":"r_sales_nav_display"},"type":"array","maxItems":1,"minItems":1,"title":"Required Scopes","description":"The required scopes value for this professionalnetworksourcepolicyout.","examples":[["r_sales_nav_display"]]},"connector_manifest_key":{"type":"string","const":"linkedin-sales-navigator","title":"Connector Manifest Key","description":"The connector manifest key value for this professionalnetworksourcepolicyout."},"partner_approval_required":{"type":"boolean","const":true,"title":"Partner Approval Required","description":"The partner approval required value for this professionalnetworksourcepolicyout."},"new_partner_intake_available":{"type":"boolean","const":false,"title":"New Partner Intake Available","description":"The new partner intake available value for this professionalnetworksourcepolicyout."},"availability_observed_at":{"type":"string","const":"2026-07-13","title":"Availability Observed At","description":"The availability observed at value for this professionalnetworksourcepolicyout."},"display_only":{"type":"boolean","const":true,"title":"Display Only","description":"The display only value for this professionalnetworksourcepolicyout."},"provider_content_storage_authorized":{"type":"boolean","const":false,"title":"Provider Content Storage Authorized","description":"The provider content storage authorized value for this professionalnetworksourcepolicyout."},"official_program_documentation_url":{"type":"string","title":"Official Program Documentation Url","description":"The official program documentation url value for this professionalnetworksourcepolicyout.","examples":["https://example.com"]},"official_display_documentation_url":{"type":"string","title":"Official Display Documentation Url","description":"The official display documentation url value for this professionalnetworksourcepolicyout.","examples":["https://example.com"]},"official_access_documentation_url":{"type":"string","title":"Official Access Documentation Url","description":"The official access documentation url value for this professionalnetworksourcepolicyout.","examples":["https://example.com"]},"official_api_terms_url":{"type":"string","title":"Official Api Terms Url","description":"The official api terms url value for this professionalnetworksourcepolicyout.","examples":["https://example.com"]},"official_user_agreement_url":{"type":"string","title":"Official User Agreement Url","description":"The official user agreement url value for this professionalnetworksourcepolicyout.","examples":["https://example.com"]},"maximum_members":{"type":"integer","const":25,"title":"Maximum Members","description":"The maximum members value for this professionalnetworksourcepolicyout."}},"additionalProperties":false,"type":"object","required":["provider","display_name","program","operation","integration_mode","oauth_flow","required_scopes","connector_manifest_key","partner_approval_required","new_partner_intake_available","availability_observed_at","display_only","provider_content_storage_authorized","official_program_documentation_url","official_display_documentation_url","official_access_documentation_url","official_api_terms_url","official_user_agreement_url","maximum_members"],"title":"ProfessionalNetworkSourcePolicyOut","description":"Structured professionalnetworksourcepolicyout data exposed by the public API.","examples":[{"provider":"linkedin_sales_navigator","display_name":"LinkedIn Sales Navigator","program":"sales_navigator_application_platform","operation":"display_services","integration_mode":"official_api_oauth2","oauth_flow":"member_authorization","required_scopes":["r_sales_nav_display"],"connector_manifest_key":"linkedin-sales-navigator","partner_approval_required":true,"new_partner_intake_available":false,"availability_observed_at":"2026-07-13","display_only":true,"provider_content_storage_authorized":false,"official_program_documentation_url":"https://example.com","official_display_documentation_url":"https://example.com","official_access_documentation_url":"https://example.com","official_api_terms_url":"https://example.com","official_user_agreement_url":"https://example.com","maximum_members":25}]},"ProfessionalNetworkSpecificationCreateIn":{"properties":{"key":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","title":"Key","description":"The key value for this professionalnetworkspecificationcreatein.","examples":["example-key"]},"audience_id":{"type":"string","pattern":"^audience_[a-f0-9]{24}$","title":"Audience Id","description":"The audience id value for this professionalnetworkspecificationcreatein.","examples":["audience_aaaaaaaaaaaaaaaaaaaaaaaa"]},"expected_audience_result_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Expected Audience Result Hash","description":"The expected audience result hash value for this professionalnetworkspecificationcreatein.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"selection":{"$ref":"#/components/schemas/ProfessionalNetworkSelectionIn","description":"The selection value for this professionalnetworkspecificationcreatein.","examples":[{"mode":"included"}]},"connection":{"$ref":"#/components/schemas/ProfessionalNetworkConnectionIn","description":"The connection value for this professionalnetworkspecificationcreatein.","examples":[{"connection_id":"conn_aaaaaaaaaaaaaaaaaaaaaaaa","expected_manifest_version":"2026-07-14","expected_credentials_version":1}]},"display_components":{"items":{"$ref":"#/components/schemas/ProfessionalNetworkDisplayComponent"},"type":"array","maxItems":3,"minItems":1,"title":"Display Components","description":"The display components value for this professionalnetworkspecificationcreatein.","examples":[["profile_summary"]]},"purpose":{"type":"string","const":"crm_sync","title":"Purpose","description":"The purpose value for this professionalnetworkspecificationcreatein."},"expected_policy_version":{"$ref":"#/components/schemas/ProfessionalNetworkPolicyVersion","description":"The expected policy version value for this professionalnetworkspecificationcreatein.","examples":["2026-07-13"]},"reason":{"type":"string","maxLength":500,"minLength":3,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"Reason","description":"The reason value for this professionalnetworkspecificationcreatein.","examples":["Example value"]}},"additionalProperties":false,"type":"object","required":["key","audience_id","expected_audience_result_hash","selection","connection","display_components","purpose","expected_policy_version","reason"],"title":"ProfessionalNetworkSpecificationCreateIn","description":"Freeze display intent without accepting a profile URL, handle, query, token, or row.","examples":[{"key":"example-key","audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","expected_audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","selection":{"mode":"included"},"connection":{"connection_id":"conn_aaaaaaaaaaaaaaaaaaaaaaaa","expected_manifest_version":"2026-07-14","expected_credentials_version":1},"display_components":["profile_summary"],"purpose":"crm_sync","expected_policy_version":"2026-07-13","reason":"Example value"}]},"ProfessionalNetworkSpecificationListOut":{"properties":{"schema_version":{"$ref":"#/components/schemas/ProfessionalNetworkSchemaVersion","description":"The schema version value for this professionalnetworkspecificationlistout.","examples":["2026-07-13"]},"availability":{"type":"string","const":"contract_only","title":"Availability","description":"The availability value for this professionalnetworkspecificationlistout."},"specifications":{"items":{"$ref":"#/components/schemas/ProfessionalNetworkSpecificationOut"},"type":"array","title":"Specifications","description":"The specifications value for this professionalnetworkspecificationlistout.","examples":[[{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"pronet_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","selection":{"mode":"included","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"member_count":1,"member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","member_bindings":[{"id":"audmem_aaaaaaaaaaaaaaaaaaaaaaaa","source_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","review_status":"included","snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","identity_reference_present":true}]},"connection":{"connection_id":"conn_aaaaaaaaaaaaaaaaaaaaaaaa","provider_key":"linkedin-sales-navigator","manifest_version":"2026-07-14","credentials_version":1,"configured_fields":["Example configured fields","Example configured fields","Example configured fields","Example configured fields"],"status":"configured","live_verification_status":"not_run","credentials_decrypted":false,"access_token_stored":false,"member_password_stored":false,"browser_session_stored":false},"source_policy":{"provider":"linkedin_sales_navigator","display_name":"LinkedIn Sales Navigator","program":"sales_navigator_application_platform","operation":"display_services","integration_mode":"official_api_oauth2","oauth_flow":"member_authorization","required_scopes":["r_sales_nav_display"],"connector_manifest_key":"linkedin-sales-navigator","partner_approval_required":true,"new_partner_intake_available":false,"availability_observed_at":"2026-07-13","display_only":true,"provider_content_storage_authorized":false,"official_program_documentation_url":"https://example.com","official_display_documentation_url":"https://example.com","official_access_documentation_url":"https://example.com","official_api_terms_url":"https://example.com","official_user_agreement_url":"https://example.com","maximum_members":25},"display_components":["profile_summary"],"purpose":"crm_sync","policy_version":"2026-07-13","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"provider_requests_made":0,"network_requests_made":0,"browser_requests_made":0,"profiles_matched":0,"profiles_displayed":0,"provider_records_read":0,"provider_content_stored":false,"non_official_content_accepted":false,"raw_profile_url_accepted":false,"raw_profile_handle_accepted":false,"raw_search_query_accepted":false,"member_credentials_accepted":false,"session_cookie_accepted":false,"browser_automation_available":false,"login_automation_available":false,"profile_scraping_available":false,"company_scraping_available":false,"post_scraping_available":false,"job_scraping_available":false,"contact_extraction_available":false,"email_extraction_available":false,"message_send_authorized":false,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}]]},"total":{"type":"integer","maximum":1000.0,"minimum":0.0,"title":"Total","description":"The total value for this professionalnetworkspecificationlistout.","examples":[0]},"limit":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Limit","description":"The limit value for this professionalnetworkspecificationlistout.","examples":[1]},"offset":{"type":"integer","maximum":10000.0,"minimum":0.0,"title":"Offset","description":"The offset value for this professionalnetworkspecificationlistout.","examples":[0]},"execution_available":{"type":"boolean","const":false,"title":"Execution Available","description":"The execution available value for this professionalnetworkspecificationlistout."},"provider_requests_made":{"type":"integer","const":0,"title":"Provider Requests Made","description":"The provider requests made value for this professionalnetworkspecificationlistout."},"profiles_displayed":{"type":"integer","const":0,"title":"Profiles Displayed","description":"The profiles displayed value for this professionalnetworkspecificationlistout."},"provider_content_stored":{"type":"boolean","const":false,"title":"Provider Content Stored","description":"The provider content stored value for this professionalnetworkspecificationlistout."}},"additionalProperties":false,"type":"object","required":["schema_version","availability","specifications","total","limit","offset","execution_available","provider_requests_made","profiles_displayed","provider_content_stored"],"title":"ProfessionalNetworkSpecificationListOut","description":"Structured professionalnetworkspecificationlistout data exposed by the public API.","examples":[{"schema_version":"2026-07-13","availability":"contract_only","specifications":[{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"pronet_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","selection":{"mode":"included","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"member_count":1,"member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","member_bindings":[{"id":"audmem_aaaaaaaaaaaaaaaaaaaaaaaa","source_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","review_status":"included","snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","identity_reference_present":true}]},"connection":{"connection_id":"conn_aaaaaaaaaaaaaaaaaaaaaaaa","provider_key":"linkedin-sales-navigator","manifest_version":"2026-07-14","credentials_version":1,"configured_fields":["Example configured fields","Example configured fields","Example configured fields","Example configured fields"],"status":"configured","live_verification_status":"not_run","credentials_decrypted":false,"access_token_stored":false,"member_password_stored":false,"browser_session_stored":false},"source_policy":{"provider":"linkedin_sales_navigator","display_name":"LinkedIn Sales Navigator","program":"sales_navigator_application_platform","operation":"display_services","integration_mode":"official_api_oauth2","oauth_flow":"member_authorization","required_scopes":["r_sales_nav_display"],"connector_manifest_key":"linkedin-sales-navigator","partner_approval_required":true,"new_partner_intake_available":false,"availability_observed_at":"2026-07-13","display_only":true,"provider_content_storage_authorized":false,"official_program_documentation_url":"https://example.com","official_display_documentation_url":"https://example.com","official_access_documentation_url":"https://example.com","official_api_terms_url":"https://example.com","official_user_agreement_url":"https://example.com","maximum_members":25},"display_components":["profile_summary"],"purpose":"crm_sync","policy_version":"2026-07-13","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"provider_requests_made":0,"network_requests_made":0,"browser_requests_made":0,"profiles_matched":0,"profiles_displayed":0,"provider_records_read":0,"provider_content_stored":false,"non_official_content_accepted":false,"raw_profile_url_accepted":false,"raw_profile_handle_accepted":false,"raw_search_query_accepted":false,"member_credentials_accepted":false,"session_cookie_accepted":false,"browser_automation_available":false,"login_automation_available":false,"profile_scraping_available":false,"company_scraping_available":false,"post_scraping_available":false,"job_scraping_available":false,"contact_extraction_available":false,"email_extraction_available":false,"message_send_authorized":false,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}],"total":0,"limit":1,"offset":0,"execution_available":false,"provider_requests_made":0,"profiles_displayed":0,"provider_content_stored":false}]},"ProfessionalNetworkSpecificationOut":{"properties":{"schema_version":{"$ref":"#/components/schemas/ProfessionalNetworkSchemaVersion","description":"The schema version value for this professionalnetworkspecificationout.","examples":["2026-07-13"]},"status":{"type":"string","const":"specified","title":"Status","description":"The status value for this professionalnetworkspecificationout."},"availability":{"type":"string","const":"contract_only","title":"Availability","description":"The availability value for this professionalnetworkspecificationout."},"id":{"type":"string","pattern":"^pronet_[a-f0-9]{24}$","title":"Id","description":"The id value for this professionalnetworkspecificationout.","examples":["pronet_aaaaaaaaaaaaaaaaaaaaaaaa"]},"idempotent_replay":{"type":"boolean","title":"Idempotent Replay","description":"The idempotent replay value for this professionalnetworkspecificationout.","examples":[true]},"key":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","title":"Key","description":"The key value for this professionalnetworkspecificationout.","examples":["example-key"]},"project_id":{"type":"string","pattern":"^proj_[a-f0-9]{24}$","title":"Project Id","description":"The project id value for this professionalnetworkspecificationout.","examples":["proj_aaaaaaaaaaaaaaaaaaaaaaaa"]},"environment":{"type":"string","enum":["live","test"],"title":"Environment","description":"The environment value for this professionalnetworkspecificationout.","examples":["live"]},"audience_id":{"type":"string","pattern":"^audience_[a-f0-9]{24}$","title":"Audience Id","description":"The audience id value for this professionalnetworkspecificationout.","examples":["audience_aaaaaaaaaaaaaaaaaaaaaaaa"]},"audience_result_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Audience Result Hash","description":"The audience result hash value for this professionalnetworkspecificationout.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"selection":{"$ref":"#/components/schemas/ProfessionalNetworkSelectionOut","description":"The selection value for this professionalnetworkspecificationout.","examples":[{"mode":"included","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"member_count":1,"member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","member_bindings":[{"id":"audmem_aaaaaaaaaaaaaaaaaaaaaaaa","source_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","review_status":"included","snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","identity_reference_present":true}]}]},"connection":{"$ref":"#/components/schemas/ProfessionalNetworkConnectionBindingOut","description":"The connection value for this professionalnetworkspecificationout.","examples":[{"connection_id":"conn_aaaaaaaaaaaaaaaaaaaaaaaa","provider_key":"linkedin-sales-navigator","manifest_version":"2026-07-14","credentials_version":1,"configured_fields":["Example configured fields","Example configured fields","Example configured fields","Example configured fields"],"status":"configured","live_verification_status":"not_run","credentials_decrypted":false,"access_token_stored":false,"member_password_stored":false,"browser_session_stored":false}]},"source_policy":{"$ref":"#/components/schemas/ProfessionalNetworkSourcePolicyOut","description":"The source policy value for this professionalnetworkspecificationout.","examples":[{"provider":"linkedin_sales_navigator","display_name":"LinkedIn Sales Navigator","program":"sales_navigator_application_platform","operation":"display_services","integration_mode":"official_api_oauth2","oauth_flow":"member_authorization","required_scopes":["r_sales_nav_display"],"connector_manifest_key":"linkedin-sales-navigator","partner_approval_required":true,"new_partner_intake_available":false,"availability_observed_at":"2026-07-13","display_only":true,"provider_content_storage_authorized":false,"official_program_documentation_url":"https://example.com","official_display_documentation_url":"https://example.com","official_access_documentation_url":"https://example.com","official_api_terms_url":"https://example.com","official_user_agreement_url":"https://example.com","maximum_members":25}]},"display_components":{"items":{"$ref":"#/components/schemas/ProfessionalNetworkDisplayComponent"},"type":"array","maxItems":3,"minItems":1,"title":"Display Components","description":"The display components value for this professionalnetworkspecificationout.","examples":[["profile_summary"]]},"purpose":{"$ref":"#/components/schemas/ProfessionalNetworkPurpose","description":"The purpose value for this professionalnetworkspecificationout.","examples":["crm_sync"]},"policy_version":{"$ref":"#/components/schemas/ProfessionalNetworkPolicyVersion","description":"The policy version value for this professionalnetworkspecificationout.","examples":["2026-07-13"]},"specification_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Specification Hash","description":"The specification hash value for this professionalnetworkspecificationout.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"reason":{"type":"string","maxLength":500,"minLength":3,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"Reason","description":"The reason value for this professionalnetworkspecificationout.","examples":["Example value"]},"execution_available":{"type":"boolean","const":false,"title":"Execution Available","description":"The execution available value for this professionalnetworkspecificationout."},"execution_authorized":{"type":"boolean","const":false,"title":"Execution Authorized","description":"The execution authorized value for this professionalnetworkspecificationout."},"provider_requests_made":{"type":"integer","const":0,"title":"Provider Requests Made","description":"The provider requests made value for this professionalnetworkspecificationout."},"network_requests_made":{"type":"integer","const":0,"title":"Network Requests Made","description":"The network requests made value for this professionalnetworkspecificationout."},"browser_requests_made":{"type":"integer","const":0,"title":"Browser Requests Made","description":"The browser requests made value for this professionalnetworkspecificationout."},"profiles_matched":{"type":"integer","const":0,"title":"Profiles Matched","description":"The profiles matched value for this professionalnetworkspecificationout."},"profiles_displayed":{"type":"integer","const":0,"title":"Profiles Displayed","description":"The profiles displayed value for this professionalnetworkspecificationout."},"provider_records_read":{"type":"integer","const":0,"title":"Provider Records Read","description":"The provider records read value for this professionalnetworkspecificationout."},"provider_content_stored":{"type":"boolean","const":false,"title":"Provider Content Stored","description":"The provider content stored value for this professionalnetworkspecificationout."},"non_official_content_accepted":{"type":"boolean","const":false,"title":"Non Official Content Accepted","description":"The non official content accepted value for this professionalnetworkspecificationout."},"raw_profile_url_accepted":{"type":"boolean","const":false,"title":"Raw Profile Url Accepted","description":"The raw profile url accepted value for this professionalnetworkspecificationout."},"raw_profile_handle_accepted":{"type":"boolean","const":false,"title":"Raw Profile Handle Accepted","description":"The raw profile handle accepted value for this professionalnetworkspecificationout."},"raw_search_query_accepted":{"type":"boolean","const":false,"title":"Raw Search Query Accepted","description":"The raw search query accepted value for this professionalnetworkspecificationout."},"member_credentials_accepted":{"type":"boolean","const":false,"title":"Member Credentials Accepted","description":"The member credentials accepted value for this professionalnetworkspecificationout."},"session_cookie_accepted":{"type":"boolean","const":false,"title":"Session Cookie Accepted","description":"The session cookie accepted value for this professionalnetworkspecificationout."},"browser_automation_available":{"type":"boolean","const":false,"title":"Browser Automation Available","description":"The browser automation available value for this professionalnetworkspecificationout."},"login_automation_available":{"type":"boolean","const":false,"title":"Login Automation Available","description":"The login automation available value for this professionalnetworkspecificationout."},"profile_scraping_available":{"type":"boolean","const":false,"title":"Profile Scraping Available","description":"The profile scraping available value for this professionalnetworkspecificationout."},"company_scraping_available":{"type":"boolean","const":false,"title":"Company Scraping Available","description":"The company scraping available value for this professionalnetworkspecificationout."},"post_scraping_available":{"type":"boolean","const":false,"title":"Post Scraping Available","description":"The post scraping available value for this professionalnetworkspecificationout."},"job_scraping_available":{"type":"boolean","const":false,"title":"Job Scraping Available","description":"The job scraping available value for this professionalnetworkspecificationout."},"contact_extraction_available":{"type":"boolean","const":false,"title":"Contact Extraction Available","description":"The contact extraction available value for this professionalnetworkspecificationout."},"email_extraction_available":{"type":"boolean","const":false,"title":"Email Extraction Available","description":"The email extraction available value for this professionalnetworkspecificationout."},"message_send_authorized":{"type":"boolean","const":false,"title":"Message Send Authorized","description":"The message send authorized value for this professionalnetworkspecificationout."},"export_authorized":{"type":"boolean","const":false,"title":"Export Authorized","description":"The export authorized value for this professionalnetworkspecificationout."},"outbound_authorized":{"type":"boolean","const":false,"title":"Outbound Authorized","description":"The outbound authorized value for this professionalnetworkspecificationout."},"crm_mutation_authorized":{"type":"boolean","const":false,"title":"Crm Mutation Authorized","description":"The crm mutation authorized value for this professionalnetworkspecificationout."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"The created at value for this professionalnetworkspecificationout.","examples":["2026-07-16T00:00:00Z"]}},"additionalProperties":false,"type":"object","required":["schema_version","status","availability","id","idempotent_replay","key","project_id","environment","audience_id","audience_result_hash","selection","connection","source_policy","display_components","purpose","policy_version","specification_hash","reason","execution_available","execution_authorized","provider_requests_made","network_requests_made","browser_requests_made","profiles_matched","profiles_displayed","provider_records_read","provider_content_stored","non_official_content_accepted","raw_profile_url_accepted","raw_profile_handle_accepted","raw_search_query_accepted","member_credentials_accepted","session_cookie_accepted","browser_automation_available","login_automation_available","profile_scraping_available","company_scraping_available","post_scraping_available","job_scraping_available","contact_extraction_available","email_extraction_available","message_send_authorized","export_authorized","outbound_authorized","crm_mutation_authorized","created_at"],"title":"ProfessionalNetworkSpecificationOut","description":"Structured professionalnetworkspecificationout data exposed by the public API.","examples":[{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"pronet_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","selection":{"mode":"included","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"member_count":1,"member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","member_bindings":[{"id":"audmem_aaaaaaaaaaaaaaaaaaaaaaaa","source_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","review_status":"included","snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","identity_reference_present":true}]},"connection":{"connection_id":"conn_aaaaaaaaaaaaaaaaaaaaaaaa","provider_key":"linkedin-sales-navigator","manifest_version":"2026-07-14","credentials_version":1,"configured_fields":["Example configured fields","Example configured fields","Example configured fields","Example configured fields"],"status":"configured","live_verification_status":"not_run","credentials_decrypted":false,"access_token_stored":false,"member_password_stored":false,"browser_session_stored":false},"source_policy":{"provider":"linkedin_sales_navigator","display_name":"LinkedIn Sales Navigator","program":"sales_navigator_application_platform","operation":"display_services","integration_mode":"official_api_oauth2","oauth_flow":"member_authorization","required_scopes":["r_sales_nav_display"],"connector_manifest_key":"linkedin-sales-navigator","partner_approval_required":true,"new_partner_intake_available":false,"availability_observed_at":"2026-07-13","display_only":true,"provider_content_storage_authorized":false,"official_program_documentation_url":"https://example.com","official_display_documentation_url":"https://example.com","official_access_documentation_url":"https://example.com","official_api_terms_url":"https://example.com","official_user_agreement_url":"https://example.com","maximum_members":25},"display_components":["profile_summary"],"purpose":"crm_sync","policy_version":"2026-07-13","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"provider_requests_made":0,"network_requests_made":0,"browser_requests_made":0,"profiles_matched":0,"profiles_displayed":0,"provider_records_read":0,"provider_content_stored":false,"non_official_content_accepted":false,"raw_profile_url_accepted":false,"raw_profile_handle_accepted":false,"raw_search_query_accepted":false,"member_credentials_accepted":false,"session_cookie_accepted":false,"browser_automation_available":false,"login_automation_available":false,"profile_scraping_available":false,"company_scraping_available":false,"post_scraping_available":false,"job_scraping_available":false,"contact_extraction_available":false,"email_extraction_available":false,"message_send_authorized":false,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}]},"Prospect":{"properties":{"id":{"type":"string","maxLength":120,"minLength":1,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"Id","description":"The id value for this prospect.","examples":["Example value"]},"external_id":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"External Id","description":"The external id value for this prospect.","examples":["Example external id"]},"is_synthetic":{"type":"boolean","title":"Is Synthetic","default":false,"description":"The is synthetic value for this prospect."},"profile":{"$ref":"#/components/schemas/ProspectProfile","description":"The profile value for this prospect.","examples":[{"company":{}}]},"qualification":{"$ref":"#/components/schemas/Qualification","description":"The qualification value for this prospect.","examples":[{"status":"qualified","score":0.0,"confidence":0.0,"reason":"Example reason","selection_strategy":"cold_start"}]},"enrichment":{"$ref":"#/components/schemas/ProspectEnrichment","description":"The enrichment value for this prospect.","examples":[{"status":"not_requested"}]},"outreach":{"$ref":"#/components/schemas/ProspectOutreach","description":"The outreach value for this prospect.","examples":[{"state":"not_ready"}]},"evidence":{"items":{"$ref":"#/components/schemas/EvidenceRef"},"type":"array","maxItems":200,"title":"Evidence","description":"The evidence value for this prospect.","examples":[[{"id":"Example id","source":"web","label":"Example label","confidence":0.0}]]}},"type":"object","required":["id","profile","qualification","enrichment","outreach"],"title":"Prospect","description":"Structured prospect data exposed by the public API.","examples":[{"id":"Example value","profile":{"company":{}},"qualification":{"status":"qualified","score":0.0,"confidence":0.0,"reason":"Example reason","selection_strategy":"cold_start"},"enrichment":{"status":"not_requested"},"outreach":{"state":"not_ready"}}]},"ProspectCompany":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":240},{"type":"null"}],"title":"Name","description":"The name value for this prospectcompany.","examples":["Example name"]},"domain":{"anyOf":[{"type":"string","maxLength":253},{"type":"null"}],"title":"Domain","description":"The domain value for this prospectcompany.","examples":["Example domain"]},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Description","description":"The description value for this prospectcompany.","examples":["Example description"]},"industry":{"anyOf":[{"type":"string","maxLength":240},{"type":"null"}],"title":"Industry","description":"The industry value for this prospectcompany.","examples":["Example industry"]},"headcount":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Headcount","description":"The headcount value for this prospectcompany.","examples":[0]},"location":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Location","description":"The location value for this prospectcompany.","examples":["Example location"]}},"type":"object","title":"ProspectCompany","description":"Structured prospectcompany data exposed by the public API.","examples":[{}]},"ProspectEnrichment":{"properties":{"status":{"type":"string","enum":["not_requested","pending","found","not_found","failed"],"title":"Status","description":"The status value for this prospectenrichment.","examples":["not_requested"]},"work_email":{"anyOf":[{"type":"string","maxLength":320},{"type":"null"}],"title":"Work Email","description":"The work email value for this prospectenrichment.","examples":["Example work email"]},"confidence":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Confidence","description":"The confidence value for this prospectenrichment.","examples":[0.0]},"evidence_ids":{"items":{"type":"string"},"type":"array","maxItems":100,"title":"Evidence Ids","description":"The evidence ids value for this prospectenrichment.","examples":[["Example evidence ids"]]}},"type":"object","required":["status"],"title":"ProspectEnrichment","description":"Structured prospectenrichment data exposed by the public API.","examples":[{"status":"not_requested"}]},"ProspectIdentityOut":{"properties":{"prospecting_job_id":{"type":"string","pattern":"^job_[a-f0-9]{24}$","title":"Prospecting Job Id","description":"The prospecting job id value for this prospectidentityout.","examples":["job_aaaaaaaaaaaaaaaaaaaaaaaa"]},"prospect_id":{"type":"string","maxLength":120,"minLength":1,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"Prospect Id","description":"The prospect id value for this prospectidentityout.","examples":["Example value"]},"full_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Full Name","description":"The full name value for this prospectidentityout.","examples":["Example full name"]},"job_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Title","description":"The job title value for this prospectidentityout.","examples":["Example job title"]},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name","description":"The company name value for this prospectidentityout.","examples":["Example company name"]},"work_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Work Email","description":"The work email value for this prospectidentityout.","examples":["Example work email"]},"is_synthetic":{"type":"boolean","title":"Is Synthetic","description":"The is synthetic value for this prospectidentityout.","examples":[true]}},"additionalProperties":false,"type":"object","required":["prospecting_job_id","prospect_id","is_synthetic"],"title":"ProspectIdentityOut","description":"Structured prospectidentityout data exposed by the public API.","examples":[{"prospecting_job_id":"job_aaaaaaaaaaaaaaaaaaaaaaaa","prospect_id":"Example value","is_synthetic":true}]},"ProspectMessageGenerateIn":{"properties":{"operation":{"type":"string","const":"prospect_personalization","title":"Operation","default":"prospect_personalization","description":"The operation value for this prospectmessagegeneratein."},"environment":{"type":"string","enum":["live","test"],"title":"Environment","default":"live","description":"The environment value for this prospectmessagegeneratein."},"template_revision_id":{"anyOf":[{"type":"string","pattern":"^msgtemplate_[a-f0-9]{24}$"},{"type":"null"}],"title":"Template Revision Id","description":"The template revision id value for this prospectmessagegeneratein.","examples":["msgtemplate_aaaaaaaaaaaaaaaaaaaaaaaa"]},"prospecting_job_id":{"type":"string","pattern":"^job_[a-f0-9]{24}$","title":"Prospecting Job Id","description":"The prospecting job id value for this prospectmessagegeneratein.","examples":["job_aaaaaaaaaaaaaaaaaaaaaaaa"]},"prospect_id":{"type":"string","maxLength":120,"minLength":1,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"Prospect Id","description":"The prospect id value for this prospectmessagegeneratein.","examples":["Example value"]},"sender":{"anyOf":[{"$ref":"#/components/schemas/SenderIdentity"},{"type":"null"}],"description":"The sender value for this prospectmessagegeneratein.","examples":[{"name":"Example name","company":"Example company","reply_email":"Example reply email"}]},"compliance":{"$ref":"#/components/schemas/ComplianceContext","description":"The compliance value for this prospectmessagegeneratein.","examples":[{}]},"trigger":{"anyOf":[{"$ref":"#/components/schemas/EvidenceStatement"},{"type":"null"}],"description":"The trigger value for this prospectmessagegeneratein.","examples":[{"text":"Example text","source_url":"https://example.com","observed_at":"Example observed at"}]},"role_priority":{"anyOf":[{"type":"string","maxLength":500,"minLength":1},{"type":"null"}],"title":"Role Priority","description":"The role priority value for this prospectmessagegeneratein.","examples":["Example role priority"]},"why_now":{"anyOf":[{"type":"string","maxLength":500,"minLength":1},{"type":"null"}],"title":"Why Now","description":"The why now value for this prospectmessagegeneratein.","examples":["Example why now"]},"problem_hypothesis":{"anyOf":[{"type":"string","maxLength":4000,"minLength":1},{"type":"null"}],"title":"Problem Hypothesis","description":"The problem hypothesis value for this prospectmessagegeneratein.","examples":["Example problem hypothesis"]},"problem_hypothesis_evidence":{"anyOf":[{"type":"string","maxLength":4000,"minLength":1},{"type":"null"}],"title":"Problem Hypothesis Evidence","description":"The problem hypothesis evidence value for this prospectmessagegeneratein.","examples":["Example problem hypothesis evidence"]},"offer_summary":{"anyOf":[{"type":"string","maxLength":4000,"minLength":1},{"type":"null"}],"title":"Offer Summary","description":"The offer summary value for this prospectmessagegeneratein.","examples":["Example offer summary"]},"proof_point":{"anyOf":[{"type":"string","maxLength":500,"minLength":1},{"type":"null"}],"title":"Proof Point","description":"The proof point value for this prospectmessagegeneratein.","examples":["Example proof point"]},"proof_source_url":{"anyOf":[{"type":"string","maxLength":2000,"minLength":8,"pattern":"^https?://"},{"type":"null"}],"title":"Proof Source Url","description":"The proof source url value for this prospectmessagegeneratein.","examples":["https://example.com"]},"proof_approved_for_external_use":{"type":"boolean","title":"Proof Approved For External Use","default":false,"description":"The proof approved for external use value for this prospectmessagegeneratein."},"proof_similarity":{"anyOf":[{"type":"string","maxLength":500,"minLength":1},{"type":"null"}],"title":"Proof Similarity","description":"The proof similarity value for this prospectmessagegeneratein.","examples":["Example proof similarity"]},"desired_next_step":{"anyOf":[{"type":"string","maxLength":500,"minLength":1},{"type":"null"}],"title":"Desired Next Step","description":"The desired next step value for this prospectmessagegeneratein.","examples":["Example desired next step"]},"tone":{"anyOf":[{"type":"string","enum":["direct","warm","consultative","technical"]},{"type":"null"}],"title":"Tone","description":"The tone value for this prospectmessagegeneratein.","examples":["direct"]},"max_words":{"anyOf":[{"type":"integer","maximum":120.0,"minimum":50.0},{"type":"null"}],"title":"Max Words","description":"The max words value for this prospectmessagegeneratein.","examples":[50]},"max_links":{"anyOf":[{"type":"integer","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Max Links","description":"The max links value for this prospectmessagegeneratein.","examples":[0]},"demonstration_mode":{"type":"boolean","title":"Demonstration Mode","default":false,"description":"The demonstration mode value for this prospectmessagegeneratein."},"reason":{"type":"string","maxLength":500,"minLength":3,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"Reason","description":"The reason value for this prospectmessagegeneratein.","examples":["Example value"]}},"additionalProperties":false,"type":"object","required":["prospecting_job_id","prospect_id","reason"],"title":"ProspectMessageGenerateIn","description":"Generate a no-send personalized draft from one retained prospect result.","examples":[{"prospecting_job_id":"job_aaaaaaaaaaaaaaaaaaaaaaaa","prospect_id":"Example value","reason":"Example value"}]},"ProspectMessageResult":{"properties":{"schema_version":{"type":"string","const":"2026-07-20","title":"Schema Version","default":"2026-07-20","description":"The schema version value for this prospectmessageresult."},"operation":{"type":"string","const":"prospect_personalization","title":"Operation","default":"prospect_personalization","description":"The operation value for this prospectmessageresult."},"status":{"type":"string","enum":["DRAFT_READY","NEEDS_INPUT","BLOCKED","DEMONSTRATION_ONLY"],"title":"Status","description":"The status value for this prospectmessageresult.","examples":["DRAFT_READY"]},"status_reasons":{"items":{"type":"string"},"type":"array","maxItems":30,"title":"Status Reasons","description":"The status reasons value for this prospectmessageresult.","examples":[["Example status reasons"]]},"prospect":{"$ref":"#/components/schemas/ProspectIdentityOut","description":"The prospect value for this prospectmessageresult.","examples":[{"prospecting_job_id":"job_aaaaaaaaaaaaaaaaaaaaaaaa","prospect_id":"Example value","is_synthetic":true}]},"template_revision_id":{"type":"string","pattern":"^msgtemplate_[a-f0-9]{24}$","title":"Template Revision Id","description":"The template revision id value for this prospectmessageresult.","examples":["msgtemplate_aaaaaaaaaaaaaaaaaaaaaaaa"]},"template_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Template Hash","description":"The template hash value for this prospectmessageresult.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"subject_options":{"items":{"type":"string"},"type":"array","maxItems":3,"title":"Subject Options","description":"The subject options value for this prospectmessageresult.","examples":[["Example subject options"]]},"recommended_subject":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Recommended Subject","description":"The recommended subject value for this prospectmessageresult.","examples":["Example recommended subject"]},"text_body":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}],"title":"Text Body","description":"The text body value for this prospectmessageresult.","examples":["Example text body"]},"word_count":{"type":"integer","maximum":10000.0,"minimum":0.0,"title":"Word Count","default":0,"description":"The word count value for this prospectmessageresult."},"link_count":{"type":"integer","maximum":20.0,"minimum":0.0,"title":"Link Count","default":0,"description":"The link count value for this prospectmessageresult."},"quality":{"anyOf":[{"$ref":"#/components/schemas/QualityScore"},{"type":"null"}],"description":"The quality value for this prospectmessageresult.","examples":[{"relevance":0,"evidence":0,"clarity":0,"recipient_value":0,"cta":0,"trust":0,"mobile_readability":0,"total":0,"passed":true}]},"recipient_fit":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Recipient Fit","description":"The recipient fit value for this prospectmessageresult.","examples":["Example recipient fit"]},"evidence_used":{"anyOf":[{"$ref":"#/components/schemas/EvidenceUsedOut"},{"type":"null"}],"description":"The evidence used value for this prospectmessageresult.","examples":[{"text":"Example text","confidence":0.0}]},"compliance_verification":{"anyOf":[{"$ref":"#/components/schemas/ComplianceVerificationOut"},{"type":"null"}],"description":"Platform-derived policy, evidence, provenance, and suppression facts for a real prospect.","examples":[{"basis_evidence_verified":true,"policy_reference":"POL-OUTREACH-4.2","policy_verified":true,"policy_version":"2026.07","source_provenance_verified":true,"suppressed":false,"suppression_checked_at":"2026-07-20T03:00:00Z","verification_source":"platform_policy_evidence_and_outcome_ledgers","verified_address_source":"provider_verified"}]},"preconditions":{"items":{"type":"string"},"type":"array","maxItems":30,"title":"Preconditions","description":"The preconditions value for this prospectmessageresult.","examples":[["Example preconditions"]]},"experiment_note":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Experiment Note","description":"The experiment note value for this prospectmessageresult.","examples":["Example experiment note"]},"approval_artifact":{"anyOf":[{"$ref":"#/components/schemas/MessageApprovalArtifact"},{"type":"null"}],"description":"The approval artifact value for this prospectmessageresult.","examples":[{"artifact_id":"msgart_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","artifact_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}]},"generated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Generated At","description":"The generated at value for this prospectmessageresult.","examples":["2026-07-16T00:00:00Z"]},"approval_required":{"type":"boolean","const":true,"title":"Approval Required","default":true,"description":"The approval required value for this prospectmessageresult."},"messages_enqueued":{"type":"integer","const":0,"title":"Messages Enqueued","default":0,"description":"The messages enqueued value for this prospectmessageresult."},"messages_sent":{"type":"integer","const":0,"title":"Messages Sent","default":0,"description":"The messages sent value for this prospectmessageresult."},"outbound_authorized":{"type":"boolean","const":false,"title":"Outbound Authorized","default":false,"description":"The outbound authorized value for this prospectmessageresult."}},"additionalProperties":false,"type":"object","required":["status","prospect","template_revision_id","template_hash"],"title":"ProspectMessageResult","description":"Structured prospectmessageresult data exposed by the public API.","examples":[{"status":"DRAFT_READY","prospect":{"prospecting_job_id":"job_aaaaaaaaaaaaaaaaaaaaaaaa","prospect_id":"Example value","is_synthetic":true},"template_revision_id":"msgtemplate_aaaaaaaaaaaaaaaaaaaaaaaa","template_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}]},"ProspectOutreach":{"properties":{"state":{"type":"string","enum":["not_ready","ready_to_contact"],"title":"State","description":"The state value for this prospectoutreach.","examples":["not_ready"]},"draft":{"anyOf":[{"$ref":"#/components/schemas/OutreachDraft"},{"type":"null"}],"description":"The draft value for this prospectoutreach.","examples":[{"subject":"Example subject","body":"Example body"}]}},"type":"object","required":["state"],"title":"ProspectOutreach","description":"Structured prospectoutreach data exposed by the public API.","examples":[{"state":"not_ready"}]},"ProspectProfile":{"properties":{"full_name":{"anyOf":[{"type":"string","maxLength":240},{"type":"null"}],"title":"Full Name","description":"The full name value for this prospectprofile.","examples":["Example full name"]},"headline":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Headline","description":"The headline value for this prospectprofile.","examples":["Example headline"]},"job_title":{"anyOf":[{"type":"string","maxLength":240},{"type":"null"}],"title":"Job Title","description":"The job title value for this prospectprofile.","examples":["Example job title"]},"seniority":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Seniority","description":"The seniority value for this prospectprofile.","examples":["Example seniority"]},"location":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Location","description":"The location value for this prospectprofile.","examples":["Example location"]},"profile_url":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Profile Url","description":"The profile url value for this prospectprofile.","examples":["https://example.com"]},"company":{"$ref":"#/components/schemas/ProspectCompany","description":"The company value for this prospectprofile.","examples":[{}]}},"type":"object","required":["company"],"title":"ProspectProfile","description":"Structured prospectprofile data exposed by the public API.","examples":[{"company":{}}]},"ProspectResearchAnalysisPolicyOut":{"properties":{"source_content_classification":{"type":"string","const":"untrusted_data","title":"Source Content Classification","description":"The source content classification value for this prospectresearchanalysispolicyout."},"embedded_instruction_handling":{"type":"string","const":"ignore","title":"Embedded Instruction Handling","description":"The embedded instruction handling value for this prospectresearchanalysispolicyout."},"claim_evidence_binding":{"type":"string","const":"required","title":"Claim Evidence Binding","description":"The claim evidence binding value for this prospectresearchanalysispolicyout."},"unsupported_claim_handling":{"type":"string","const":"omit","title":"Unsupported Claim Handling","description":"The unsupported claim handling value for this prospectresearchanalysispolicyout."},"conflicting_evidence_handling":{"type":"string","const":"retain_and_flag","title":"Conflicting Evidence Handling","description":"The conflicting evidence handling value for this prospectresearchanalysispolicyout."},"model_output_validation":{"type":"string","const":"required","title":"Model Output Validation","description":"The model output validation value for this prospectresearchanalysispolicyout."},"prompt_template_version":{"type":"string","const":"prospect-research-2026-07-14","title":"Prompt Template Version","description":"The prompt template version value for this prospectresearchanalysispolicyout."},"model_identity_recording_required":{"type":"boolean","const":true,"title":"Model Identity Recording Required","description":"The model identity recording required value for this prospectresearchanalysispolicyout."},"prompt_hash_recording_required":{"type":"boolean","const":true,"title":"Prompt Hash Recording Required","description":"The prompt hash recording required value for this prospectresearchanalysispolicyout."},"source_snapshot_hash_recording_required":{"type":"boolean","const":true,"title":"Source Snapshot Hash Recording Required","description":"The source snapshot hash recording required value for this prospectresearchanalysispolicyout."},"forbidden_inferences":{"items":{"$ref":"#/components/schemas/ProspectResearchForbiddenInference"},"type":"array","maxItems":12,"minItems":12,"title":"Forbidden Inferences","description":"The forbidden inferences value for this prospectresearchanalysispolicyout.","examples":[["creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness"]]},"scoring_or_ranking_allowed":{"type":"boolean","const":false,"title":"Scoring Or Ranking Allowed","description":"The scoring or ranking allowed value for this prospectresearchanalysispolicyout."},"outreach_generation_allowed":{"type":"boolean","const":false,"title":"Outreach Generation Allowed","description":"The outreach generation allowed value for this prospectresearchanalysispolicyout."},"hiring_or_investing_decision_support_allowed":{"type":"boolean","const":false,"title":"Hiring Or Investing Decision Support Allowed","description":"The hiring or investing decision support allowed value for this prospectresearchanalysispolicyout."}},"additionalProperties":false,"type":"object","required":["source_content_classification","embedded_instruction_handling","claim_evidence_binding","unsupported_claim_handling","conflicting_evidence_handling","model_output_validation","prompt_template_version","model_identity_recording_required","prompt_hash_recording_required","source_snapshot_hash_recording_required","forbidden_inferences","scoring_or_ranking_allowed","outreach_generation_allowed","hiring_or_investing_decision_support_allowed"],"title":"ProspectResearchAnalysisPolicyOut","description":"Structured prospectresearchanalysispolicyout data exposed by the public API.","examples":[{"source_content_classification":"untrusted_data","embedded_instruction_handling":"ignore","claim_evidence_binding":"required","unsupported_claim_handling":"omit","conflicting_evidence_handling":"retain_and_flag","model_output_validation":"required","prompt_template_version":"prospect-research-2026-07-14","model_identity_recording_required":true,"prompt_hash_recording_required":true,"source_snapshot_hash_recording_required":true,"forbidden_inferences":["creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness"],"scoring_or_ranking_allowed":false,"outreach_generation_allowed":false,"hiring_or_investing_decision_support_allowed":false}]},"ProspectResearchBudgetOut":{"properties":{"max_provider_requests_per_member":{"type":"integer","maximum":12.0,"minimum":0.0,"title":"Max Provider Requests Per Member","description":"The max provider requests per member value for this prospectresearchbudgetout.","examples":[0]},"max_model_requests_per_member":{"type":"integer","const":1,"title":"Max Model Requests Per Member","description":"The max model requests per member value for this prospectresearchbudgetout."},"max_agent_tool_calls_per_member":{"type":"integer","maximum":3.0,"minimum":0.0,"title":"Max Agent Tool Calls Per Member","description":"The max agent tool calls per member value for this prospectresearchbudgetout.","examples":[0]},"max_evidence_items_per_member":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Max Evidence Items Per Member","description":"The max evidence items per member value for this prospectresearchbudgetout.","examples":[1]},"max_model_input_chars_per_member":{"type":"integer","maximum":50000.0,"minimum":1000.0,"title":"Max Model Input Chars Per Member","description":"The max model input chars per member value for this prospectresearchbudgetout.","examples":[1000]},"member_count":{"type":"integer","maximum":25.0,"minimum":1.0,"title":"Member Count","description":"The member count value for this prospectresearchbudgetout.","examples":[1]},"max_total_provider_requests":{"type":"integer","maximum":300.0,"minimum":0.0,"title":"Max Total Provider Requests","description":"The max total provider requests value for this prospectresearchbudgetout.","examples":[0]},"max_total_model_requests":{"type":"integer","maximum":25.0,"minimum":1.0,"title":"Max Total Model Requests","description":"The max total model requests value for this prospectresearchbudgetout.","examples":[1]},"max_total_agent_tool_calls":{"type":"integer","maximum":75.0,"minimum":0.0,"title":"Max Total Agent Tool Calls","description":"The max total agent tool calls value for this prospectresearchbudgetout.","examples":[0]},"hard_limits_required":{"type":"boolean","const":true,"title":"Hard Limits Required","description":"The hard limits required value for this prospectresearchbudgetout."},"quota_reserved":{"type":"boolean","const":false,"title":"Quota Reserved","description":"The quota reserved value for this prospectresearchbudgetout."}},"additionalProperties":false,"type":"object","required":["max_provider_requests_per_member","max_model_requests_per_member","max_agent_tool_calls_per_member","max_evidence_items_per_member","max_model_input_chars_per_member","member_count","max_total_provider_requests","max_total_model_requests","max_total_agent_tool_calls","hard_limits_required","quota_reserved"],"title":"ProspectResearchBudgetOut","description":"Structured prospectresearchbudgetout data exposed by the public API.","examples":[{"max_provider_requests_per_member":0,"max_model_requests_per_member":1,"max_agent_tool_calls_per_member":0,"max_evidence_items_per_member":1,"max_model_input_chars_per_member":1000,"member_count":1,"max_total_provider_requests":0,"max_total_model_requests":1,"max_total_agent_tool_calls":0,"hard_limits_required":true,"quota_reserved":false}]},"ProspectResearchCollectionBudgetIn":{"properties":{"max_provider_requests_per_member":{"type":"integer","maximum":12.0,"minimum":0.0,"title":"Max Provider Requests Per Member","description":"The max provider requests per member value for this prospectresearchcollectionbudgetin.","examples":[0]},"max_model_requests_per_member":{"type":"integer","const":1,"title":"Max Model Requests Per Member","description":"The max model requests per member value for this prospectresearchcollectionbudgetin."},"max_agent_tool_calls_per_member":{"type":"integer","maximum":3.0,"minimum":0.0,"title":"Max Agent Tool Calls Per Member","description":"The max agent tool calls per member value for this prospectresearchcollectionbudgetin.","examples":[0]},"max_evidence_items_per_member":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Max Evidence Items Per Member","description":"The max evidence items per member value for this prospectresearchcollectionbudgetin.","examples":[1]},"max_model_input_chars_per_member":{"type":"integer","maximum":50000.0,"minimum":1000.0,"title":"Max Model Input Chars Per Member","description":"The max model input chars per member value for this prospectresearchcollectionbudgetin.","examples":[1000]}},"additionalProperties":false,"type":"object","required":["max_provider_requests_per_member","max_model_requests_per_member","max_agent_tool_calls_per_member","max_evidence_items_per_member","max_model_input_chars_per_member"],"title":"ProspectResearchCollectionBudgetIn","description":"Hard ceilings for a future executor; this contract reserves no quota.","examples":[{"max_provider_requests_per_member":0,"max_model_requests_per_member":1,"max_agent_tool_calls_per_member":0,"max_evidence_items_per_member":1,"max_model_input_chars_per_member":1000}]},"ProspectResearchEvidenceType":{"type":"string","enum":["audience_evidence","dated_business_activity","dated_business_statement"],"title":"ProspectResearchEvidenceType","description":"Structured prospectresearchevidencetype data exposed by the public API.","examples":["audience_evidence"]},"ProspectResearchForbiddenInference":{"type":"string","enum":["creditworthiness","family_status","health","hidden_interests","personality","political_beliefs","protected_attributes","psychometrics","religious_beliefs","sexual_orientation","union_membership","values"],"title":"ProspectResearchForbiddenInference","description":"Structured prospectresearchforbiddeninference data exposed by the public API.","examples":["creditworthiness"]},"ProspectResearchLens":{"type":"string","enum":["business_priorities","content_themes","expertise_evidence","professional_challenges","recent_trigger_events"],"title":"ProspectResearchLens","description":"Structured prospectresearchlens data exposed by the public API.","examples":["business_priorities"]},"ProspectResearchLensSpecOut":{"properties":{"lens":{"$ref":"#/components/schemas/ProspectResearchLens","description":"The lens value for this prospectresearchlensspecout.","examples":["business_priorities"]},"claim_type":{"type":"string","title":"Claim Type","description":"The claim type value for this prospectresearchlensspecout.","examples":["Example claim type"]},"description":{"type":"string","title":"Description","description":"The description value for this prospectresearchlensspecout.","examples":["Example description"]},"allowed_evidence_types":{"items":{"$ref":"#/components/schemas/ProspectResearchEvidenceType"},"type":"array","maxItems":3,"minItems":1,"title":"Allowed Evidence Types","description":"The allowed evidence types value for this prospectresearchlensspecout.","examples":[["audience_evidence"]]},"maximum_evidence_age_days":{"type":"integer","maximum":3650.0,"minimum":1.0,"title":"Maximum Evidence Age Days","description":"The maximum evidence age days value for this prospectresearchlensspecout.","examples":[1]},"minimum_evidence_items_per_claim":{"type":"integer","const":1,"title":"Minimum Evidence Items Per Claim","description":"The minimum evidence items per claim value for this prospectresearchlensspecout."},"explicit_evidence_only":{"type":"boolean","const":true,"title":"Explicit Evidence Only","description":"The explicit evidence only value for this prospectresearchlensspecout."},"unsupported_behavior":{"type":"string","const":"omit","title":"Unsupported Behavior","description":"The unsupported behavior value for this prospectresearchlensspecout."}},"additionalProperties":false,"type":"object","required":["lens","claim_type","description","allowed_evidence_types","maximum_evidence_age_days","minimum_evidence_items_per_claim","explicit_evidence_only","unsupported_behavior"],"title":"ProspectResearchLensSpecOut","description":"Structured prospectresearchlensspecout data exposed by the public API.","examples":[{"lens":"business_priorities","claim_type":"Example claim type","description":"Example description","allowed_evidence_types":["audience_evidence"],"maximum_evidence_age_days":1,"minimum_evidence_items_per_claim":1,"explicit_evidence_only":true,"unsupported_behavior":"omit"}]},"ProspectResearchMemberBindingOut":{"properties":{"id":{"type":"string","pattern":"^audmem_[a-f0-9]{24}$","title":"Id","description":"The id value for this prospectresearchmemberbindingout.","examples":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"]},"source_result_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Source Result Hash","description":"The source result hash value for this prospectresearchmemberbindingout.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"review_status":{"type":"string","const":"included","title":"Review Status","description":"The review status value for this prospectresearchmemberbindingout."},"snapshot_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Snapshot Hash","description":"The snapshot hash value for this prospectresearchmemberbindingout.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"identity_reference_present":{"type":"boolean","const":true,"title":"Identity Reference Present","description":"The identity reference present value for this prospectresearchmemberbindingout."}},"additionalProperties":false,"type":"object","required":["id","source_result_hash","review_status","snapshot_hash","identity_reference_present"],"title":"ProspectResearchMemberBindingOut","description":"Structured prospectresearchmemberbindingout data exposed by the public API.","examples":[{"id":"audmem_aaaaaaaaaaaaaaaaaaaaaaaa","source_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","review_status":"included","snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","identity_reference_present":true}]},"ProspectResearchPolicyVersion":{"type":"string","enum":["2026-07-15"],"title":"ProspectResearchPolicyVersion","description":"Readable/replayable research policies; append versions, never replace them.","examples":["2026-07-15"]},"ProspectResearchPurpose":{"type":"string","enum":["qualification"],"title":"ProspectResearchPurpose","description":"Structured prospectresearchpurpose data exposed by the public API.","examples":["qualification"]},"ProspectResearchResultContractOut":{"properties":{"schema_version":{"type":"string","const":"2026-07-15","title":"Schema Version","description":"The schema version value for this prospectresearchresultcontractout."},"result_shape":{"type":"string","const":"member_evidence_claim_sets","title":"Result Shape","description":"The result shape value for this prospectresearchresultcontractout."},"member_reference_field":{"type":"string","const":"audience_member_id","title":"Member Reference Field","description":"The member reference field value for this prospectresearchresultcontractout."},"claim_fields":{"items":{"type":"string","enum":["lens","claim","confidence","evidence_ids","status"]},"type":"array","title":"Claim Fields","description":"The claim fields value for this prospectresearchresultcontractout.","examples":[["lens"]]},"evidence_fields":{"items":{"type":"string","enum":["evidence_id","source_snapshot_hash","observed_at","excerpt_hash"]},"type":"array","title":"Evidence Fields","description":"The evidence fields value for this prospectresearchresultcontractout.","examples":[["evidence_id"]]},"unsupported_lens_status":{"type":"string","const":"unsupported","title":"Unsupported Lens Status","description":"The unsupported lens status value for this prospectresearchresultcontractout."},"citations_required":{"type":"boolean","const":true,"title":"Citations Required","description":"The citations required value for this prospectresearchresultcontractout."},"raw_source_payload_returned":{"type":"boolean","const":false,"title":"Raw Source Payload Returned","description":"The raw source payload returned value for this prospectresearchresultcontractout."}},"additionalProperties":false,"type":"object","required":["schema_version","result_shape","member_reference_field","claim_fields","evidence_fields","unsupported_lens_status","citations_required","raw_source_payload_returned"],"title":"ProspectResearchResultContractOut","description":"Structured prospectresearchresultcontractout data exposed by the public API.","examples":[{"schema_version":"2026-07-15","result_shape":"member_evidence_claim_sets","member_reference_field":"audience_member_id","claim_fields":["lens"],"evidence_fields":["evidence_id"],"unsupported_lens_status":"unsupported","citations_required":true,"raw_source_payload_returned":false}]},"ProspectResearchSchemaVersion":{"type":"string","enum":["2026-07-15"],"title":"ProspectResearchSchemaVersion","description":"Readable historical response schemas; append versions, never replace them.","examples":["2026-07-15"]},"ProspectResearchSelectionIn":{"properties":{"mode":{"$ref":"#/components/schemas/ProspectResearchSelectionMode","description":"The mode value for this prospectresearchselectionin.","examples":["included"]},"member_ids":{"items":{"type":"string","pattern":"^audmem_[a-f0-9]{24}$"},"type":"array","maxItems":25,"title":"Member Ids","description":"The member ids value for this prospectresearchselectionin.","examples":[["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"]]}},"additionalProperties":false,"type":"object","required":["mode"],"title":"ProspectResearchSelectionIn","description":"Select all reviewed members or one exact reviewed subset.","examples":[{"mode":"included"}]},"ProspectResearchSelectionMode":{"type":"string","enum":["included","explicit"],"title":"ProspectResearchSelectionMode","description":"Structured prospectresearchselectionmode data exposed by the public API.","examples":["included"]},"ProspectResearchSelectionOut":{"properties":{"mode":{"$ref":"#/components/schemas/ProspectResearchSelectionMode","description":"The mode value for this prospectresearchselectionout.","examples":["included"]},"member_ids":{"items":{"type":"string","pattern":"^audmem_[a-f0-9]{24}$"},"type":"array","maxItems":25,"minItems":1,"title":"Member Ids","description":"The member ids value for this prospectresearchselectionout.","examples":[["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"]]},"member_count":{"type":"integer","maximum":25.0,"minimum":1.0,"title":"Member Count","description":"The member count value for this prospectresearchselectionout.","examples":[1]},"member_snapshot_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Member Snapshot Hash","description":"The member snapshot hash value for this prospectresearchselectionout.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"member_bindings":{"items":{"$ref":"#/components/schemas/ProspectResearchMemberBindingOut"},"type":"array","maxItems":25,"minItems":1,"title":"Member Bindings","description":"The member bindings value for this prospectresearchselectionout.","examples":[[{"id":"audmem_aaaaaaaaaaaaaaaaaaaaaaaa","source_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","review_status":"included","snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","identity_reference_present":true}]]}},"additionalProperties":false,"type":"object","required":["mode","member_ids","member_count","member_snapshot_hash","member_bindings"],"title":"ProspectResearchSelectionOut","description":"Structured prospectresearchselectionout data exposed by the public API.","examples":[{"mode":"included","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"member_count":1,"member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","member_bindings":[{"id":"audmem_aaaaaaaaaaaaaaaaaaaaaaaa","source_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","review_status":"included","snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","identity_reference_present":true}]}]},"ProspectResearchSourceRequirementsOut":{"properties":{"permitted_purpose":{"type":"string","const":"qualification","title":"Permitted Purpose","description":"The permitted purpose value for this prospectresearchsourcerequirementsout."},"credentials_in_specification_accepted":{"type":"boolean","const":false,"title":"Credentials In Specification Accepted","description":"The credentials in specification accepted value for this prospectresearchsourcerequirementsout."},"public_web_allowed":{"type":"boolean","const":false,"title":"Public Web Allowed","description":"The public web allowed value for this prospectresearchsourcerequirementsout."},"restricted_broker_allowed":{"type":"boolean","const":false,"title":"Restricted Broker Allowed","description":"The restricted broker allowed value for this prospectresearchsourcerequirementsout."},"automated_scraping_allowed":{"type":"boolean","const":false,"title":"Automated Scraping Allowed","description":"The automated scraping allowed value for this prospectresearchsourcerequirementsout."},"raw_third_party_aggregates_allowed":{"type":"boolean","const":false,"title":"Raw Third Party Aggregates Allowed","description":"The raw third party aggregates allowed value for this prospectresearchsourcerequirementsout."}},"additionalProperties":false,"type":"object","required":["permitted_purpose","credentials_in_specification_accepted","public_web_allowed","restricted_broker_allowed","automated_scraping_allowed","raw_third_party_aggregates_allowed"],"title":"ProspectResearchSourceRequirementsOut","description":"Descriptive source policy for any future executor; no registry lookup is implied.","examples":[{"permitted_purpose":"qualification","credentials_in_specification_accepted":false,"public_web_allowed":false,"restricted_broker_allowed":false,"automated_scraping_allowed":false,"raw_third_party_aggregates_allowed":false}]},"ProspectResearchSpecificationCreateIn":{"properties":{"key":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","title":"Key","description":"The key value for this prospectresearchspecificationcreatein.","examples":["example-key"]},"audience_id":{"type":"string","pattern":"^audience_[a-f0-9]{24}$","title":"Audience Id","description":"The audience id value for this prospectresearchspecificationcreatein.","examples":["audience_aaaaaaaaaaaaaaaaaaaaaaaa"]},"expected_audience_result_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Expected Audience Result Hash","description":"The expected audience result hash value for this prospectresearchspecificationcreatein.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"selection":{"$ref":"#/components/schemas/ProspectResearchSelectionIn","description":"The selection value for this prospectresearchspecificationcreatein.","examples":[{"mode":"included"}]},"lenses":{"items":{"$ref":"#/components/schemas/ProspectResearchLens"},"type":"array","maxItems":5,"minItems":1,"title":"Lenses","description":"The lenses value for this prospectresearchspecificationcreatein.","examples":[["business_priorities"]]},"collection_budget":{"$ref":"#/components/schemas/ProspectResearchCollectionBudgetIn","description":"The collection budget value for this prospectresearchspecificationcreatein.","examples":[{"max_provider_requests_per_member":0,"max_model_requests_per_member":1,"max_agent_tool_calls_per_member":0,"max_evidence_items_per_member":1,"max_model_input_chars_per_member":1000}]},"purpose":{"type":"string","const":"qualification","title":"Purpose","description":"The purpose value for this prospectresearchspecificationcreatein."},"expected_policy_version":{"$ref":"#/components/schemas/ProspectResearchPolicyVersion","description":"The expected policy version value for this prospectresearchspecificationcreatein.","examples":["2026-07-15"]},"reason":{"type":"string","maxLength":500,"minLength":3,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"Reason","description":"The reason value for this prospectresearchspecificationcreatein.","examples":["Example value"]}},"additionalProperties":false,"type":"object","required":["key","audience_id","expected_audience_result_hash","selection","lenses","collection_budget","purpose","expected_policy_version","reason"],"title":"ProspectResearchSpecificationCreateIn","description":"Freeze safe research intent without accepting URLs, prompts, traits, or source rows.","examples":[{"key":"example-key","audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","expected_audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","selection":{"mode":"included"},"lenses":["business_priorities"],"collection_budget":{"max_provider_requests_per_member":0,"max_model_requests_per_member":1,"max_agent_tool_calls_per_member":0,"max_evidence_items_per_member":1,"max_model_input_chars_per_member":1000},"purpose":"qualification","expected_policy_version":"2026-07-15","reason":"Example value"}]},"ProspectResearchSpecificationListOut":{"properties":{"schema_version":{"$ref":"#/components/schemas/ProspectResearchSchemaVersion","description":"The schema version value for this prospectresearchspecificationlistout.","examples":["2026-07-15"]},"availability":{"type":"string","const":"contract_only","title":"Availability","description":"The availability value for this prospectresearchspecificationlistout."},"specifications":{"items":{"$ref":"#/components/schemas/ProspectResearchSpecificationOut"},"type":"array","title":"Specifications","description":"The specifications value for this prospectresearchspecificationlistout.","examples":[[{"schema_version":"2026-07-15","status":"specified","availability":"contract_only","id":"prosresearch_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","selection":{"mode":"included","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"member_count":1,"member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","member_bindings":[{"id":"audmem_aaaaaaaaaaaaaaaaaaaaaaaa","source_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","review_status":"included","snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","identity_reference_present":true}]},"source_requirements":{"permitted_purpose":"qualification","credentials_in_specification_accepted":false,"public_web_allowed":false,"restricted_broker_allowed":false,"automated_scraping_allowed":false,"raw_third_party_aggregates_allowed":false},"lenses":["business_priorities"],"lens_specs":[{"lens":"business_priorities","claim_type":"Example claim type","description":"Example description","allowed_evidence_types":["audience_evidence"],"maximum_evidence_age_days":1,"minimum_evidence_items_per_claim":1,"explicit_evidence_only":true,"unsupported_behavior":"omit"}],"collection_budget":{"max_provider_requests_per_member":0,"max_model_requests_per_member":1,"max_agent_tool_calls_per_member":0,"max_evidence_items_per_member":1,"max_model_input_chars_per_member":1000,"member_count":1,"max_total_provider_requests":0,"max_total_model_requests":1,"max_total_agent_tool_calls":0,"hard_limits_required":true,"quota_reserved":false},"analysis_policy":{"source_content_classification":"untrusted_data","embedded_instruction_handling":"ignore","claim_evidence_binding":"required","unsupported_claim_handling":"omit","conflicting_evidence_handling":"retain_and_flag","model_output_validation":"required","prompt_template_version":"prospect-research-2026-07-14","model_identity_recording_required":true,"prompt_hash_recording_required":true,"source_snapshot_hash_recording_required":true,"forbidden_inferences":["creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness"],"scoring_or_ranking_allowed":false,"outreach_generation_allowed":false,"hiring_or_investing_decision_support_allowed":false},"result_contract":{"schema_version":"2026-07-15","result_shape":"member_evidence_claim_sets","member_reference_field":"audience_member_id","claim_fields":["lens"],"evidence_fields":["evidence_id"],"unsupported_lens_status":"unsupported","citations_required":true,"raw_source_payload_returned":false},"purpose":"qualification","policy_version":"2026-07-15","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"provider_requests_made":0,"model_requests_made":0,"agent_tool_calls_made":0,"network_requests_made":0,"browser_requests_made":0,"source_records_read":0,"raw_provider_records_stored":false,"raw_profile_url_accepted":false,"raw_profile_handle_accepted":false,"raw_provider_payload_accepted":false,"arbitrary_prompt_accepted":false,"custom_insight_definition_accepted":false,"source_instructions_followed":false,"third_party_scraping_available":false,"restricted_broker_content_accepted":false,"evidence_claims_created":0,"profiles_scored":0,"profiles_ranked":0,"personality_traits_inferred":0,"protected_attributes_inferred":0,"outreach_drafts_created":0,"hiring_decisions_supported":false,"investment_decisions_supported":false,"credit_decisions_supported":false,"message_send_authorized":false,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}]]},"total":{"type":"integer","maximum":1000.0,"minimum":0.0,"title":"Total","description":"The total value for this prospectresearchspecificationlistout.","examples":[0]},"limit":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Limit","description":"The limit value for this prospectresearchspecificationlistout.","examples":[1]},"offset":{"type":"integer","maximum":10000.0,"minimum":0.0,"title":"Offset","description":"The offset value for this prospectresearchspecificationlistout.","examples":[0]},"execution_available":{"type":"boolean","const":false,"title":"Execution Available","description":"The execution available value for this prospectresearchspecificationlistout."},"provider_requests_made":{"type":"integer","const":0,"title":"Provider Requests Made","description":"The provider requests made value for this prospectresearchspecificationlistout."},"model_requests_made":{"type":"integer","const":0,"title":"Model Requests Made","description":"The model requests made value for this prospectresearchspecificationlistout."},"evidence_claims_created":{"type":"integer","const":0,"title":"Evidence Claims Created","description":"The evidence claims created value for this prospectresearchspecificationlistout."},"raw_provider_records_stored":{"type":"boolean","const":false,"title":"Raw Provider Records Stored","description":"The raw provider records stored value for this prospectresearchspecificationlistout."}},"additionalProperties":false,"type":"object","required":["schema_version","availability","specifications","total","limit","offset","execution_available","provider_requests_made","model_requests_made","evidence_claims_created","raw_provider_records_stored"],"title":"ProspectResearchSpecificationListOut","description":"Structured prospectresearchspecificationlistout data exposed by the public API.","examples":[{"schema_version":"2026-07-15","availability":"contract_only","specifications":[{"schema_version":"2026-07-15","status":"specified","availability":"contract_only","id":"prosresearch_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","selection":{"mode":"included","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"member_count":1,"member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","member_bindings":[{"id":"audmem_aaaaaaaaaaaaaaaaaaaaaaaa","source_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","review_status":"included","snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","identity_reference_present":true}]},"source_requirements":{"permitted_purpose":"qualification","credentials_in_specification_accepted":false,"public_web_allowed":false,"restricted_broker_allowed":false,"automated_scraping_allowed":false,"raw_third_party_aggregates_allowed":false},"lenses":["business_priorities"],"lens_specs":[{"lens":"business_priorities","claim_type":"Example claim type","description":"Example description","allowed_evidence_types":["audience_evidence"],"maximum_evidence_age_days":1,"minimum_evidence_items_per_claim":1,"explicit_evidence_only":true,"unsupported_behavior":"omit"}],"collection_budget":{"max_provider_requests_per_member":0,"max_model_requests_per_member":1,"max_agent_tool_calls_per_member":0,"max_evidence_items_per_member":1,"max_model_input_chars_per_member":1000,"member_count":1,"max_total_provider_requests":0,"max_total_model_requests":1,"max_total_agent_tool_calls":0,"hard_limits_required":true,"quota_reserved":false},"analysis_policy":{"source_content_classification":"untrusted_data","embedded_instruction_handling":"ignore","claim_evidence_binding":"required","unsupported_claim_handling":"omit","conflicting_evidence_handling":"retain_and_flag","model_output_validation":"required","prompt_template_version":"prospect-research-2026-07-14","model_identity_recording_required":true,"prompt_hash_recording_required":true,"source_snapshot_hash_recording_required":true,"forbidden_inferences":["creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness"],"scoring_or_ranking_allowed":false,"outreach_generation_allowed":false,"hiring_or_investing_decision_support_allowed":false},"result_contract":{"schema_version":"2026-07-15","result_shape":"member_evidence_claim_sets","member_reference_field":"audience_member_id","claim_fields":["lens"],"evidence_fields":["evidence_id"],"unsupported_lens_status":"unsupported","citations_required":true,"raw_source_payload_returned":false},"purpose":"qualification","policy_version":"2026-07-15","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"provider_requests_made":0,"model_requests_made":0,"agent_tool_calls_made":0,"network_requests_made":0,"browser_requests_made":0,"source_records_read":0,"raw_provider_records_stored":false,"raw_profile_url_accepted":false,"raw_profile_handle_accepted":false,"raw_provider_payload_accepted":false,"arbitrary_prompt_accepted":false,"custom_insight_definition_accepted":false,"source_instructions_followed":false,"third_party_scraping_available":false,"restricted_broker_content_accepted":false,"evidence_claims_created":0,"profiles_scored":0,"profiles_ranked":0,"personality_traits_inferred":0,"protected_attributes_inferred":0,"outreach_drafts_created":0,"hiring_decisions_supported":false,"investment_decisions_supported":false,"credit_decisions_supported":false,"message_send_authorized":false,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}],"total":0,"limit":1,"offset":0,"execution_available":false,"provider_requests_made":0,"model_requests_made":0,"evidence_claims_created":0,"raw_provider_records_stored":false}]},"ProspectResearchSpecificationOut":{"properties":{"schema_version":{"$ref":"#/components/schemas/ProspectResearchSchemaVersion","description":"The schema version value for this prospectresearchspecificationout.","examples":["2026-07-15"]},"status":{"type":"string","const":"specified","title":"Status","description":"The status value for this prospectresearchspecificationout."},"availability":{"type":"string","const":"contract_only","title":"Availability","description":"The availability value for this prospectresearchspecificationout."},"id":{"type":"string","pattern":"^prosresearch_[a-f0-9]{24}$","title":"Id","description":"The id value for this prospectresearchspecificationout.","examples":["prosresearch_aaaaaaaaaaaaaaaaaaaaaaaa"]},"idempotent_replay":{"type":"boolean","title":"Idempotent Replay","description":"The idempotent replay value for this prospectresearchspecificationout.","examples":[true]},"key":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","title":"Key","description":"The key value for this prospectresearchspecificationout.","examples":["example-key"]},"project_id":{"type":"string","pattern":"^proj_[a-f0-9]{24}$","title":"Project Id","description":"The project id value for this prospectresearchspecificationout.","examples":["proj_aaaaaaaaaaaaaaaaaaaaaaaa"]},"environment":{"type":"string","enum":["live","test"],"title":"Environment","description":"The environment value for this prospectresearchspecificationout.","examples":["live"]},"audience_id":{"type":"string","pattern":"^audience_[a-f0-9]{24}$","title":"Audience Id","description":"The audience id value for this prospectresearchspecificationout.","examples":["audience_aaaaaaaaaaaaaaaaaaaaaaaa"]},"audience_result_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Audience Result Hash","description":"The audience result hash value for this prospectresearchspecificationout.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"selection":{"$ref":"#/components/schemas/ProspectResearchSelectionOut","description":"The selection value for this prospectresearchspecificationout.","examples":[{"mode":"included","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"member_count":1,"member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","member_bindings":[{"id":"audmem_aaaaaaaaaaaaaaaaaaaaaaaa","source_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","review_status":"included","snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","identity_reference_present":true}]}]},"source_requirements":{"$ref":"#/components/schemas/ProspectResearchSourceRequirementsOut","description":"The source requirements value for this prospectresearchspecificationout.","examples":[{"permitted_purpose":"qualification","credentials_in_specification_accepted":false,"public_web_allowed":false,"restricted_broker_allowed":false,"automated_scraping_allowed":false,"raw_third_party_aggregates_allowed":false}]},"lenses":{"items":{"$ref":"#/components/schemas/ProspectResearchLens"},"type":"array","maxItems":5,"minItems":1,"title":"Lenses","description":"The lenses value for this prospectresearchspecificationout.","examples":[["business_priorities"]]},"lens_specs":{"items":{"$ref":"#/components/schemas/ProspectResearchLensSpecOut"},"type":"array","maxItems":5,"minItems":1,"title":"Lens Specs","description":"The lens specs value for this prospectresearchspecificationout.","examples":[[{"lens":"business_priorities","claim_type":"Example claim type","description":"Example description","allowed_evidence_types":["audience_evidence"],"maximum_evidence_age_days":1,"minimum_evidence_items_per_claim":1,"explicit_evidence_only":true,"unsupported_behavior":"omit"}]]},"collection_budget":{"$ref":"#/components/schemas/ProspectResearchBudgetOut","description":"The collection budget value for this prospectresearchspecificationout.","examples":[{"max_provider_requests_per_member":0,"max_model_requests_per_member":1,"max_agent_tool_calls_per_member":0,"max_evidence_items_per_member":1,"max_model_input_chars_per_member":1000,"member_count":1,"max_total_provider_requests":0,"max_total_model_requests":1,"max_total_agent_tool_calls":0,"hard_limits_required":true,"quota_reserved":false}]},"analysis_policy":{"$ref":"#/components/schemas/ProspectResearchAnalysisPolicyOut","description":"The analysis policy value for this prospectresearchspecificationout.","examples":[{"source_content_classification":"untrusted_data","embedded_instruction_handling":"ignore","claim_evidence_binding":"required","unsupported_claim_handling":"omit","conflicting_evidence_handling":"retain_and_flag","model_output_validation":"required","prompt_template_version":"prospect-research-2026-07-14","model_identity_recording_required":true,"prompt_hash_recording_required":true,"source_snapshot_hash_recording_required":true,"forbidden_inferences":["creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness"],"scoring_or_ranking_allowed":false,"outreach_generation_allowed":false,"hiring_or_investing_decision_support_allowed":false}]},"result_contract":{"$ref":"#/components/schemas/ProspectResearchResultContractOut","description":"The result contract value for this prospectresearchspecificationout.","examples":[{"schema_version":"2026-07-15","result_shape":"member_evidence_claim_sets","member_reference_field":"audience_member_id","claim_fields":["lens"],"evidence_fields":["evidence_id"],"unsupported_lens_status":"unsupported","citations_required":true,"raw_source_payload_returned":false}]},"purpose":{"$ref":"#/components/schemas/ProspectResearchPurpose","description":"The purpose value for this prospectresearchspecificationout.","examples":["qualification"]},"policy_version":{"$ref":"#/components/schemas/ProspectResearchPolicyVersion","description":"The policy version value for this prospectresearchspecificationout.","examples":["2026-07-15"]},"specification_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Specification Hash","description":"The specification hash value for this prospectresearchspecificationout.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"reason":{"type":"string","maxLength":500,"minLength":3,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"Reason","description":"The reason value for this prospectresearchspecificationout.","examples":["Example value"]},"execution_available":{"type":"boolean","const":false,"title":"Execution Available","description":"The execution available value for this prospectresearchspecificationout."},"execution_authorized":{"type":"boolean","const":false,"title":"Execution Authorized","description":"The execution authorized value for this prospectresearchspecificationout."},"provider_requests_made":{"type":"integer","const":0,"title":"Provider Requests Made","description":"The provider requests made value for this prospectresearchspecificationout."},"model_requests_made":{"type":"integer","const":0,"title":"Model Requests Made","description":"The model requests made value for this prospectresearchspecificationout."},"agent_tool_calls_made":{"type":"integer","const":0,"title":"Agent Tool Calls Made","description":"The agent tool calls made value for this prospectresearchspecificationout."},"network_requests_made":{"type":"integer","const":0,"title":"Network Requests Made","description":"The network requests made value for this prospectresearchspecificationout."},"browser_requests_made":{"type":"integer","const":0,"title":"Browser Requests Made","description":"The browser requests made value for this prospectresearchspecificationout."},"source_records_read":{"type":"integer","const":0,"title":"Source Records Read","description":"The source records read value for this prospectresearchspecificationout."},"raw_provider_records_stored":{"type":"boolean","const":false,"title":"Raw Provider Records Stored","description":"The raw provider records stored value for this prospectresearchspecificationout."},"raw_profile_url_accepted":{"type":"boolean","const":false,"title":"Raw Profile Url Accepted","description":"The raw profile url accepted value for this prospectresearchspecificationout."},"raw_profile_handle_accepted":{"type":"boolean","const":false,"title":"Raw Profile Handle Accepted","description":"The raw profile handle accepted value for this prospectresearchspecificationout."},"raw_provider_payload_accepted":{"type":"boolean","const":false,"title":"Raw Provider Payload Accepted","description":"The raw provider payload accepted value for this prospectresearchspecificationout."},"arbitrary_prompt_accepted":{"type":"boolean","const":false,"title":"Arbitrary Prompt Accepted","description":"The arbitrary prompt accepted value for this prospectresearchspecificationout."},"custom_insight_definition_accepted":{"type":"boolean","const":false,"title":"Custom Insight Definition Accepted","description":"The custom insight definition accepted value for this prospectresearchspecificationout."},"source_instructions_followed":{"type":"boolean","const":false,"title":"Source Instructions Followed","description":"The source instructions followed value for this prospectresearchspecificationout."},"third_party_scraping_available":{"type":"boolean","const":false,"title":"Third Party Scraping Available","description":"The third party scraping available value for this prospectresearchspecificationout."},"restricted_broker_content_accepted":{"type":"boolean","const":false,"title":"Restricted Broker Content Accepted","description":"The restricted broker content accepted value for this prospectresearchspecificationout."},"evidence_claims_created":{"type":"integer","const":0,"title":"Evidence Claims Created","description":"The evidence claims created value for this prospectresearchspecificationout."},"profiles_scored":{"type":"integer","const":0,"title":"Profiles Scored","description":"The profiles scored value for this prospectresearchspecificationout."},"profiles_ranked":{"type":"integer","const":0,"title":"Profiles Ranked","description":"The profiles ranked value for this prospectresearchspecificationout."},"personality_traits_inferred":{"type":"integer","const":0,"title":"Personality Traits Inferred","description":"The personality traits inferred value for this prospectresearchspecificationout."},"protected_attributes_inferred":{"type":"integer","const":0,"title":"Protected Attributes Inferred","description":"The protected attributes inferred value for this prospectresearchspecificationout."},"outreach_drafts_created":{"type":"integer","const":0,"title":"Outreach Drafts Created","description":"The outreach drafts created value for this prospectresearchspecificationout."},"hiring_decisions_supported":{"type":"boolean","const":false,"title":"Hiring Decisions Supported","description":"The hiring decisions supported value for this prospectresearchspecificationout."},"investment_decisions_supported":{"type":"boolean","const":false,"title":"Investment Decisions Supported","description":"The investment decisions supported value for this prospectresearchspecificationout."},"credit_decisions_supported":{"type":"boolean","const":false,"title":"Credit Decisions Supported","description":"The credit decisions supported value for this prospectresearchspecificationout."},"message_send_authorized":{"type":"boolean","const":false,"title":"Message Send Authorized","description":"The message send authorized value for this prospectresearchspecificationout."},"export_authorized":{"type":"boolean","const":false,"title":"Export Authorized","description":"The export authorized value for this prospectresearchspecificationout."},"outbound_authorized":{"type":"boolean","const":false,"title":"Outbound Authorized","description":"The outbound authorized value for this prospectresearchspecificationout."},"crm_mutation_authorized":{"type":"boolean","const":false,"title":"Crm Mutation Authorized","description":"The crm mutation authorized value for this prospectresearchspecificationout."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"The created at value for this prospectresearchspecificationout.","examples":["2026-07-16T00:00:00Z"]}},"additionalProperties":false,"type":"object","required":["schema_version","status","availability","id","idempotent_replay","key","project_id","environment","audience_id","audience_result_hash","selection","source_requirements","lenses","lens_specs","collection_budget","analysis_policy","result_contract","purpose","policy_version","specification_hash","reason","execution_available","execution_authorized","provider_requests_made","model_requests_made","agent_tool_calls_made","network_requests_made","browser_requests_made","source_records_read","raw_provider_records_stored","raw_profile_url_accepted","raw_profile_handle_accepted","raw_provider_payload_accepted","arbitrary_prompt_accepted","custom_insight_definition_accepted","source_instructions_followed","third_party_scraping_available","restricted_broker_content_accepted","evidence_claims_created","profiles_scored","profiles_ranked","personality_traits_inferred","protected_attributes_inferred","outreach_drafts_created","hiring_decisions_supported","investment_decisions_supported","credit_decisions_supported","message_send_authorized","export_authorized","outbound_authorized","crm_mutation_authorized","created_at"],"title":"ProspectResearchSpecificationOut","description":"Structured prospectresearchspecificationout data exposed by the public API.","examples":[{"schema_version":"2026-07-15","status":"specified","availability":"contract_only","id":"prosresearch_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","audience_id":"audience_aaaaaaaaaaaaaaaaaaaaaaaa","audience_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","selection":{"mode":"included","member_ids":["audmem_aaaaaaaaaaaaaaaaaaaaaaaa"],"member_count":1,"member_snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","member_bindings":[{"id":"audmem_aaaaaaaaaaaaaaaaaaaaaaaa","source_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","review_status":"included","snapshot_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","identity_reference_present":true}]},"source_requirements":{"permitted_purpose":"qualification","credentials_in_specification_accepted":false,"public_web_allowed":false,"restricted_broker_allowed":false,"automated_scraping_allowed":false,"raw_third_party_aggregates_allowed":false},"lenses":["business_priorities"],"lens_specs":[{"lens":"business_priorities","claim_type":"Example claim type","description":"Example description","allowed_evidence_types":["audience_evidence"],"maximum_evidence_age_days":1,"minimum_evidence_items_per_claim":1,"explicit_evidence_only":true,"unsupported_behavior":"omit"}],"collection_budget":{"max_provider_requests_per_member":0,"max_model_requests_per_member":1,"max_agent_tool_calls_per_member":0,"max_evidence_items_per_member":1,"max_model_input_chars_per_member":1000,"member_count":1,"max_total_provider_requests":0,"max_total_model_requests":1,"max_total_agent_tool_calls":0,"hard_limits_required":true,"quota_reserved":false},"analysis_policy":{"source_content_classification":"untrusted_data","embedded_instruction_handling":"ignore","claim_evidence_binding":"required","unsupported_claim_handling":"omit","conflicting_evidence_handling":"retain_and_flag","model_output_validation":"required","prompt_template_version":"prospect-research-2026-07-14","model_identity_recording_required":true,"prompt_hash_recording_required":true,"source_snapshot_hash_recording_required":true,"forbidden_inferences":["creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness","creditworthiness"],"scoring_or_ranking_allowed":false,"outreach_generation_allowed":false,"hiring_or_investing_decision_support_allowed":false},"result_contract":{"schema_version":"2026-07-15","result_shape":"member_evidence_claim_sets","member_reference_field":"audience_member_id","claim_fields":["lens"],"evidence_fields":["evidence_id"],"unsupported_lens_status":"unsupported","citations_required":true,"raw_source_payload_returned":false},"purpose":"qualification","policy_version":"2026-07-15","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"provider_requests_made":0,"model_requests_made":0,"agent_tool_calls_made":0,"network_requests_made":0,"browser_requests_made":0,"source_records_read":0,"raw_provider_records_stored":false,"raw_profile_url_accepted":false,"raw_profile_handle_accepted":false,"raw_provider_payload_accepted":false,"arbitrary_prompt_accepted":false,"custom_insight_definition_accepted":false,"source_instructions_followed":false,"third_party_scraping_available":false,"restricted_broker_content_accepted":false,"evidence_claims_created":0,"profiles_scored":0,"profiles_ranked":0,"personality_traits_inferred":0,"protected_attributes_inferred":0,"outreach_drafts_created":0,"hiring_decisions_supported":false,"investment_decisions_supported":false,"credit_decisions_supported":false,"message_send_authorized":false,"export_authorized":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}]},"ProspectingCampaignResult":{"properties":{"name":{"type":"string","maxLength":160,"title":"Name","description":"The name value for this prospectingcampaignresult.","examples":["Example name"]},"status":{"type":"string","enum":["completed","partial","failed"],"title":"Status","description":"The status value for this prospectingcampaignresult.","examples":["completed"]},"delivery_mode":{"type":"string","const":"draft_only","title":"Delivery Mode","description":"The delivery mode value for this prospectingcampaignresult."},"target":{"$ref":"#/components/schemas/ProspectingTarget","description":"The target value for this prospectingcampaignresult.","examples":[{}]}},"type":"object","required":["name","status","delivery_mode","target"],"title":"ProspectingCampaignResult","description":"Structured prospectingcampaignresult data exposed by the public API.","examples":[{"name":"Example name","status":"completed","delivery_mode":"draft_only","target":{}}]},"ProspectingContinuationConstraints":{"properties":{"additional_prospect_limit":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Additional Prospect Limit","description":"The additional prospect limit value for this prospectingcontinuationconstraints.","examples":[1]},"max_rounds":{"type":"integer","maximum":10.0,"minimum":1.0,"title":"Max Rounds","default":3,"description":"The max rounds value for this prospectingcontinuationconstraints."},"min_new_prospects_per_round":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Min New Prospects Per Round","default":1,"description":"The min new prospects per round value for this prospectingcontinuationconstraints."}},"additionalProperties":false,"type":"object","required":["additional_prospect_limit"],"title":"ProspectingContinuationConstraints","description":"Structured prospectingcontinuationconstraints data exposed by the public API.","examples":[{"additional_prospect_limit":1}]},"ProspectingContinuationLineage":{"properties":{"parent_job_id":{"type":"string","pattern":"^job_[a-f0-9]{24}$","title":"Parent Job Id","description":"The parent job id value for this prospectingcontinuationlineage.","examples":["job_aaaaaaaaaaaaaaaaaaaaaaaa"]},"parent_result_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Parent Result Hash","description":"The parent result hash value for this prospectingcontinuationlineage.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"continuation_key":{"type":"string","maxLength":160,"minLength":1,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]*$","title":"Continuation Key","description":"The continuation key value for this prospectingcontinuationlineage.","examples":["example-key"]}},"additionalProperties":false,"type":"object","required":["parent_job_id","parent_result_hash","continuation_key"],"title":"ProspectingContinuationLineage","description":"Binds a continuation result to the immutable parent result and opaque key used.","examples":[{"parent_job_id":"job_aaaaaaaaaaaaaaaaaaaaaaaa","parent_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","continuation_key":"example-key"}]},"ProspectingContinuationRequest":{"properties":{"additional_prospect_limit":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Additional Prospect Limit","description":"The additional prospect limit value for this prospectingcontinuationrequest.","examples":[1]},"max_rounds":{"type":"integer","maximum":10.0,"minimum":1.0,"title":"Max Rounds","default":3,"description":"The max rounds value for this prospectingcontinuationrequest."},"min_new_prospects_per_round":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Min New Prospects Per Round","default":1,"description":"The min new prospects per round value for this prospectingcontinuationrequest."},"continuation_key":{"type":"string","maxLength":160,"minLength":1,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]*$","title":"Continuation Key","description":"The continuation key value for this prospectingcontinuationrequest.","examples":["example-key"]}},"additionalProperties":false,"type":"object","required":["additional_prospect_limit","continuation_key"],"title":"ProspectingContinuationRequest","description":"Structured prospectingcontinuationrequest data exposed by the public API.","examples":[{"additional_prospect_limit":1,"continuation_key":"example-key"}]},"ProspectingContinuationResponse":{"properties":{"id":{"type":"string","pattern":"^continuation_[a-f0-9]{24}$","title":"Id","description":"The id value for this prospectingcontinuationresponse.","examples":["continuation_aaaaaaaaaaaaaaaaaaaaaaaa"]},"status":{"type":"string","const":"accepted","title":"Status","description":"The status value for this prospectingcontinuationresponse."},"idempotent_replay":{"type":"boolean","title":"Idempotent Replay","description":"The idempotent replay value for this prospectingcontinuationresponse.","examples":[true]},"continuation_key":{"type":"string","maxLength":160,"minLength":1,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]*$","title":"Continuation Key","description":"The continuation key value for this prospectingcontinuationresponse.","examples":["example-key"]},"project_id":{"type":"string","pattern":"^proj_[a-f0-9]{24}$","title":"Project Id","description":"The project id value for this prospectingcontinuationresponse.","examples":["proj_aaaaaaaaaaaaaaaaaaaaaaaa"]},"environment":{"type":"string","enum":["live","test"],"title":"Environment","description":"The environment value for this prospectingcontinuationresponse.","examples":["live"]},"parent_job_id":{"type":"string","pattern":"^job_[a-f0-9]{24}$","title":"Parent Job Id","description":"The parent job id value for this prospectingcontinuationresponse.","examples":["job_aaaaaaaaaaaaaaaaaaaaaaaa"]},"parent_result_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Parent Result Hash","description":"The parent result hash value for this prospectingcontinuationresponse.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"constraints":{"$ref":"#/components/schemas/ProspectingContinuationConstraints","description":"The constraints value for this prospectingcontinuationresponse.","examples":[{"additional_prospect_limit":1}]},"child_job":{"$ref":"#/components/schemas/ProspectingJobResponse","description":"The child job value for this prospectingcontinuationresponse.","examples":[{"id":"job_playbook_123","status":"succeeded","progress":100,"project_id":"proj_123","usage":{"backend_requests":1,"backend_runtime_ms":1830,"cache_write_tokens":300,"cached_input_tokens":1200,"cost_usd":0.0123,"input_tokens":3500,"output_tokens":700,"reasoning_tokens":180,"tokens":4200},"created_at":"2026-07-13T12:00:00Z","expires_at":"2026-08-12T12:00:00Z","type":"prospecting","input":{"campaign_name":"Example campaign name","product_info":"Example product info","objective":"Example objective"}}]},"outbound_authorized":{"type":"boolean","const":false,"title":"Outbound Authorized","description":"The outbound authorized value for this prospectingcontinuationresponse."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"The created at value for this prospectingcontinuationresponse.","examples":["2026-07-16T00:00:00Z"]}},"additionalProperties":false,"type":"object","required":["id","status","idempotent_replay","continuation_key","project_id","environment","parent_job_id","parent_result_hash","constraints","child_job","outbound_authorized","created_at"],"title":"ProspectingContinuationResponse","description":"A child prospecting Job plus its immutable binding to the parent result.","examples":[{"id":"continuation_aaaaaaaaaaaaaaaaaaaaaaaa","status":"accepted","idempotent_replay":true,"continuation_key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","parent_job_id":"job_aaaaaaaaaaaaaaaaaaaaaaaa","parent_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","constraints":{"additional_prospect_limit":1},"child_job":{"id":"job_playbook_123","status":"succeeded","progress":100,"project_id":"proj_123","usage":{"backend_requests":1,"backend_runtime_ms":1830,"cache_write_tokens":300,"cached_input_tokens":1200,"cost_usd":0.0123,"input_tokens":3500,"output_tokens":700,"reasoning_tokens":180,"tokens":4200},"created_at":"2026-07-13T12:00:00Z","expires_at":"2026-08-12T12:00:00Z","type":"prospecting","input":{"campaign_name":"Example campaign name","product_info":"Example product info","objective":"Example objective"}},"outbound_authorized":false,"created_at":"2026-07-16T00:00:00Z"}]},"ProspectingEvidenceAttribution":{"properties":{"prospect_id":{"type":"string","maxLength":120,"minLength":1,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"Prospect Id","description":"The prospect id value for this prospectingevidenceattribution.","examples":["Example value"]},"evidence_ids":{"items":{"type":"string","maxLength":120,"minLength":1,"pattern":"^[^\\x00-\\x1f\\x7f]+$"},"type":"array","maxItems":200,"minItems":1,"title":"Evidence Ids","description":"The evidence ids value for this prospectingevidenceattribution.","examples":[["Example value"]]}},"additionalProperties":false,"type":"object","required":["prospect_id","evidence_ids"],"title":"ProspectingEvidenceAttribution","description":"Canonical evidence edges from one query attempt to one returned prospect.","examples":[{"prospect_id":"Example value","evidence_ids":["Example value"]}]},"ProspectingInput":{"properties":{"campaign_name":{"type":"string","maxLength":160,"minLength":1,"title":"Campaign Name","description":"The campaign name value for this prospectinginput.","examples":["Example campaign name"]},"product_info":{"type":"string","maxLength":12000,"minLength":1,"title":"Product Info","description":"The product info value for this prospectinginput.","examples":["Example product info"]},"objective":{"type":"string","maxLength":4000,"minLength":1,"title":"Objective","description":"The objective value for this prospectinginput.","examples":["Example objective"]},"booking_url":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Booking Url","description":"The booking url value for this prospectinginput.","examples":["https://example.com"]},"target":{"$ref":"#/components/schemas/ProspectingTarget","description":"The target value for this prospectinginput.","examples":[{}]},"limit":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Limit","default":25,"description":"The limit value for this prospectinginput."},"min_qualification_score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Min Qualification Score","default":0.9,"description":"The min qualification score value for this prospectinginput."},"delivery_mode":{"type":"string","const":"draft_only","title":"Delivery Mode","default":"draft_only","description":"The delivery mode value for this prospectinginput."},"external_ref":{"anyOf":[{"type":"string","maxLength":240},{"type":"null"}],"title":"External Ref","description":"The external ref value for this prospectinginput.","examples":["Example external ref"]},"query":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Query","description":"Natural-language brief the run uses; when omitted it is synthesized from objective, product_info and target.","examples":["Find VP Revenue Operations leaders at mid-market B2B SaaS companies in North America and draft a first-touch email."]},"mode":{"type":"string","enum":["turbo","agentic"],"title":"Mode","description":"Prospecting mode. `turbo` streams the deterministic database-search pipeline — fastest to first prospect. `agentic` engages the prospect agent, which plans the search, streams status updates and reasoning, and curates results; it requires the agentic backend and the run fails with a clear error when the connected backend does not support it (results are never fabricated).","default":"turbo","examples":["turbo"]}},"additionalProperties":false,"type":"object","required":["campaign_name","product_info","objective"],"title":"ProspectingInput","description":"Stable public contract for evidence-backed prospect discovery.\n\nProvider credentials are deliberately absent because public job inputs are stored and\nreturned to the caller. Private provider keys belong in the prospecting service's secret\nstore; callers authenticate to this gateway only with their Blackpearl project API key.","examples":[{"campaign_name":"Example campaign name","product_info":"Example product info","objective":"Example objective"}]},"ProspectingJobResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Stable asynchronous job identifier.","examples":["job_playbook_123"]},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"],"title":"Status","description":"Current job state.","examples":["succeeded"]},"progress":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Progress","description":"Coarse completion percentage. Terminal successful jobs report 100.","examples":[100]},"project_id":{"type":"string","title":"Project Id","description":"Project that owns the job and its usage.","examples":["proj_123"]},"campaign_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Campaign Id","description":"Owning Audience campaign; null for Playbooks jobs.","examples":["camp_123"]},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Stable human-readable job failure message; null unless the job failed.","examples":[null]},"error_code":{"anyOf":[{"$ref":"#/components/schemas/PublicErrorCode"},{"type":"null"}],"description":"Stable machine-readable public failure code when one applies; null otherwise.","examples":["insufficient_credits"]},"usage":{"$ref":"#/components/schemas/PublicJobUsage","description":"Usage attributed to this job.","examples":[{"backend_requests":1,"backend_runtime_ms":1830,"cache_write_tokens":300,"cached_input_tokens":1200,"cost_usd":0.0123,"input_tokens":3500,"output_tokens":700,"reasoning_tokens":180,"tokens":4200}]},"stages":{"anyOf":[{"items":{"$ref":"#/components/schemas/PublicJobStage"},"type":"array"},{"type":"null"}],"title":"Stages","description":"Ordered Audience stages; null for Playbooks jobs.","examples":[[{"key":"prelim","label":"Preliminary scoring","status":"completed"}]]},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the server accepted the job.","examples":["2026-07-13T12:00:00Z"]},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"When the job input and result leave the 30-day public retention window.","examples":["2026-08-12T12:00:00Z"]},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"When execution began; null while queued.","examples":["2026-07-13T12:00:00Z"]},"finished_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Finished At","description":"When execution reached a terminal state; null while active.","examples":["2026-07-13T12:00:00Z"]},"type":{"type":"string","const":"prospecting","title":"Type","description":"Discriminator selecting the Prospecting input and result shapes.","examples":["prospecting"]},"input":{"$ref":"#/components/schemas/ProspectingInput","description":"Typed Prospecting request snapshot retained with the job.","examples":[{"campaign_name":"Example campaign name","product_info":"Example product info","objective":"Example objective"}]},"result":{"anyOf":[{"$ref":"#/components/schemas/ProspectingResult"},{"type":"null"}],"description":"Typed Prospecting result; null until the job succeeds.","examples":[{"schema_version":"2026-07-01","campaign":{"name":"Example name","status":"completed","delivery_mode":"draft_only","target":{}},"summary":{"discovered":0,"evaluated":0,"qualified":0,"rejected":0,"enrichment_lookups":0,"emails_found":0,"drafts_created":0},"provenance":{"backend":"Example backend","schema_version":"2026-07-01"}}]}},"type":"object","required":["id","status","progress","project_id","usage","created_at","expires_at","type","input"],"title":"ProspectingJobResponse","description":"A Prospecting-specific asynchronous job response.","examples":[{"id":"job_playbook_123","status":"succeeded","progress":100,"project_id":"proj_123","usage":{"backend_requests":1,"backend_runtime_ms":1830,"cache_write_tokens":300,"cached_input_tokens":1200,"cost_usd":0.0123,"input_tokens":3500,"output_tokens":700,"reasoning_tokens":180,"tokens":4200},"created_at":"2026-07-13T12:00:00Z","expires_at":"2026-08-12T12:00:00Z","type":"prospecting","input":{"campaign_name":"Example campaign name","product_info":"Example product info","objective":"Example objective"}}]},"ProspectingProvenance":{"properties":{"backend":{"type":"string","maxLength":160,"title":"Backend","description":"The backend value for this prospectingprovenance.","examples":["Example backend"]},"schema_version":{"type":"string","const":"2026-07-01","title":"Schema Version","description":"The schema version value for this prospectingprovenance."},"model_version":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}],"title":"Model Version","description":"The model version value for this prospectingprovenance.","examples":["Example model version"]},"provider_names":{"items":{"type":"string"},"type":"array","maxItems":40,"title":"Provider Names","description":"The provider names value for this prospectingprovenance.","examples":[["Example provider names"]]}},"type":"object","required":["backend","schema_version"],"title":"ProspectingProvenance","description":"Structured prospectingprovenance data exposed by the public API.","examples":[{"backend":"Example backend","schema_version":"2026-07-01"}]},"ProspectingQueryAttempt":{"properties":{"sequence":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Sequence","description":"The sequence value for this prospectingqueryattempt.","examples":[1]},"id":{"type":"string","maxLength":120,"minLength":1,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"Id","description":"The id value for this prospectingqueryattempt.","examples":["Example value"]},"provider":{"type":"string","maxLength":160,"minLength":1,"title":"Provider","description":"The provider value for this prospectingqueryattempt.","examples":["Example provider"]},"query":{"type":"string","maxLength":2000,"minLength":1,"title":"Query","description":"The query value for this prospectingqueryattempt.","examples":["Example query"]},"status":{"$ref":"#/components/schemas/ProspectingQueryAttemptStatus","description":"The status value for this prospectingqueryattempt.","examples":["succeeded"]},"error_code":{"anyOf":[{"$ref":"#/components/schemas/ProspectingQueryErrorCode"},{"type":"null"}],"description":"The error code value for this prospectingqueryattempt.","examples":["rate_limited"]},"result_count":{"type":"integer","maximum":1000000.0,"minimum":0.0,"title":"Result Count","default":0,"description":"The result count value for this prospectingqueryattempt."},"candidate_count":{"type":"integer","maximum":1000000.0,"minimum":0.0,"title":"Candidate Count","default":0,"description":"The candidate count value for this prospectingqueryattempt."},"new_candidate_count":{"type":"integer","maximum":1000000.0,"minimum":0.0,"title":"New Candidate Count","default":0,"description":"The new candidate count value for this prospectingqueryattempt."},"new_qualified_count":{"type":"integer","maximum":1000000.0,"minimum":0.0,"title":"New Qualified Count","default":0,"description":"The new qualified count value for this prospectingqueryattempt."},"usage":{"$ref":"#/components/schemas/ProspectingQueryUsage","description":"The usage value for this prospectingqueryattempt.","examples":[{}]},"attributions":{"items":{"$ref":"#/components/schemas/ProspectingEvidenceAttribution"},"type":"array","maxItems":100,"title":"Attributions","description":"The attributions value for this prospectingqueryattempt.","examples":[[{"prospect_id":"Example value","evidence_ids":["Example value"]}]]}},"additionalProperties":false,"type":"object","required":["sequence","id","provider","query","status"],"title":"ProspectingQueryAttempt","description":"One provider query with a public, non-ambiguous terminal outcome.","examples":[{"sequence":1,"id":"Example value","provider":"Example provider","query":"Example query","status":"succeeded"}]},"ProspectingQueryAttemptStatus":{"type":"string","enum":["succeeded","no_results","rate_limited","unauthorized","unavailable","invalid_response","cancelled"],"title":"ProspectingQueryAttemptStatus","description":"Structured prospectingqueryattemptstatus data exposed by the public API.","examples":["succeeded"]},"ProspectingQueryErrorCode":{"type":"string","enum":["rate_limited","unauthorized","unavailable","invalid_response","cancelled"],"title":"ProspectingQueryErrorCode","description":"Structured prospectingqueryerrorcode data exposed by the public API.","examples":["rate_limited"]},"ProspectingQueryUsage":{"properties":{"request_count":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Request Count","default":0,"description":"The request count value for this prospectingqueryusage."},"duration_ms":{"type":"integer","maximum":86400000.0,"minimum":0.0,"title":"Duration Ms","default":0,"description":"The duration ms value for this prospectingqueryusage."},"tokens":{"type":"integer","maximum":1000000000.0,"minimum":0.0,"title":"Tokens","default":0,"description":"The tokens value for this prospectingqueryusage."},"cost_usd":{"type":"number","maximum":1000000.0,"minimum":0.0,"title":"Cost Usd","default":0.0,"description":"The cost usd value for this prospectingqueryusage."}},"additionalProperties":false,"type":"object","title":"ProspectingQueryUsage","description":"Bounded public usage totals for an attempt; no provider payloads or billing IDs.","examples":[{}]},"ProspectingResearchRound":{"properties":{"number":{"type":"integer","maximum":10.0,"minimum":1.0,"title":"Number","description":"The number value for this prospectingresearchround.","examples":[1]},"attempts":{"items":{"$ref":"#/components/schemas/ProspectingQueryAttempt"},"type":"array","maxItems":100,"minItems":1,"title":"Attempts","description":"The attempts value for this prospectingresearchround.","examples":[[{"sequence":1,"id":"Example value","provider":"Example provider","query":"Example query","status":"succeeded"}]]},"new_prospect_ids":{"items":{"type":"string","maxLength":120,"minLength":1,"pattern":"^[^\\x00-\\x1f\\x7f]+$"},"type":"array","maxItems":100,"title":"New Prospect Ids","description":"The new prospect ids value for this prospectingresearchround.","examples":[["Example value"]]}},"additionalProperties":false,"type":"object","required":["number","attempts"],"title":"ProspectingResearchRound","description":"Structured prospectingresearchround data exposed by the public API.","examples":[{"number":1,"attempts":[{"sequence":1,"id":"Example value","provider":"Example provider","query":"Example query","status":"succeeded"}]}]},"ProspectingResearchState":{"type":"string","enum":["not_reported","reported"],"title":"ProspectingResearchState","description":"Structured prospectingresearchstate data exposed by the public API.","examples":["not_reported"]},"ProspectingResearchStopReason":{"type":"string","enum":["not_reported","target_reached","max_rounds_reached","min_new_prospects_not_met","query_space_exhausted","provider_unavailable","cancelled","failed"],"title":"ProspectingResearchStopReason","description":"Structured prospectingresearchstopreason data exposed by the public API.","examples":["not_reported"]},"ProspectingResearchTrace":{"properties":{"state":{"$ref":"#/components/schemas/ProspectingResearchState","default":"not_reported","description":"The state value for this prospectingresearchtrace."},"stop_reason":{"$ref":"#/components/schemas/ProspectingResearchStopReason","default":"not_reported","description":"The stop reason value for this prospectingresearchtrace."},"rounds":{"items":{"$ref":"#/components/schemas/ProspectingResearchRound"},"type":"array","maxItems":10,"title":"Rounds","description":"The rounds value for this prospectingresearchtrace.","examples":[[{"number":1,"attempts":[{"sequence":1,"id":"Example value","provider":"Example provider","query":"Example query","status":"succeeded"}]}]]},"continuation_key":{"anyOf":[{"type":"string","maxLength":160,"minLength":1,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]*$"},{"type":"null"}],"title":"Continuation Key","description":"The continuation key value for this prospectingresearchtrace.","examples":["example-key"]}},"additionalProperties":false,"type":"object","title":"ProspectingResearchTrace","description":"Bounded, public research trace; provider payloads and internal prompts stay private.","examples":[{}]},"ProspectingResult":{"properties":{"schema_version":{"type":"string","const":"2026-07-01","title":"Schema Version","description":"The schema version value for this prospectingresult."},"campaign":{"$ref":"#/components/schemas/ProspectingCampaignResult","description":"The campaign value for this prospectingresult.","examples":[{"name":"Example name","status":"completed","delivery_mode":"draft_only","target":{}}]},"summary":{"$ref":"#/components/schemas/ProspectingSummary","description":"The summary value for this prospectingresult.","examples":[{"discovered":0,"evaluated":0,"qualified":0,"rejected":0,"enrichment_lookups":0,"emails_found":0,"drafts_created":0}]},"prospects":{"items":{"$ref":"#/components/schemas/Prospect"},"type":"array","maxItems":100,"title":"Prospects","description":"The prospects value for this prospectingresult.","examples":[[{"id":"Example value","profile":{"company":{}},"qualification":{"status":"qualified","score":0.0,"confidence":0.0,"reason":"Example reason","selection_strategy":"cold_start"},"enrichment":{"status":"not_requested"},"outreach":{"state":"not_ready"}}]]},"provenance":{"$ref":"#/components/schemas/ProspectingProvenance","description":"The provenance value for this prospectingresult.","examples":[{"backend":"Example backend","schema_version":"2026-07-01"}]},"research":{"$ref":"#/components/schemas/ProspectingResearchTrace","description":"The research value for this prospectingresult.","examples":[{}]},"continuation":{"anyOf":[{"$ref":"#/components/schemas/ProspectingContinuationLineage"},{"type":"null"}],"description":"The continuation value for this prospectingresult.","examples":[{"parent_job_id":"job_aaaaaaaaaaaaaaaaaaaaaaaa","parent_result_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","continuation_key":"example-key"}]},"external_ref":{"anyOf":[{"type":"string","maxLength":240},{"type":"null"}],"title":"External Ref","description":"The external ref value for this prospectingresult.","examples":["Example external ref"]}},"type":"object","required":["schema_version","campaign","summary","provenance"],"title":"ProspectingResult","description":"Whitelisted result; raw provider rows, prompts, untyped traces and secrets are dropped.","examples":[{"schema_version":"2026-07-01","campaign":{"name":"Example name","status":"completed","delivery_mode":"draft_only","target":{}},"summary":{"discovered":0,"evaluated":0,"qualified":0,"rejected":0,"enrichment_lookups":0,"emails_found":0,"drafts_created":0},"provenance":{"backend":"Example backend","schema_version":"2026-07-01"}}]},"ProspectingSummary":{"properties":{"discovered":{"type":"integer","minimum":0.0,"title":"Discovered","description":"The discovered value for this prospectingsummary.","examples":[0]},"evaluated":{"type":"integer","minimum":0.0,"title":"Evaluated","description":"The evaluated value for this prospectingsummary.","examples":[0]},"qualified":{"type":"integer","minimum":0.0,"title":"Qualified","description":"The qualified value for this prospectingsummary.","examples":[0]},"rejected":{"type":"integer","minimum":0.0,"title":"Rejected","description":"The rejected value for this prospectingsummary.","examples":[0]},"enrichment_lookups":{"type":"integer","minimum":0.0,"title":"Enrichment Lookups","description":"The enrichment lookups value for this prospectingsummary.","examples":[0]},"emails_found":{"type":"integer","minimum":0.0,"title":"Emails Found","description":"The emails found value for this prospectingsummary.","examples":[0]},"drafts_created":{"type":"integer","minimum":0.0,"title":"Drafts Created","description":"The drafts created value for this prospectingsummary.","examples":[0]}},"type":"object","required":["discovered","evaluated","qualified","rejected","enrichment_lookups","emails_found","drafts_created"],"title":"ProspectingSummary","description":"Structured prospectingsummary data exposed by the public API.","examples":[{"discovered":0,"evaluated":0,"qualified":0,"rejected":0,"enrichment_lookups":0,"emails_found":0,"drafts_created":0}]},"ProspectingTarget":{"properties":{"company_names":{"items":{"type":"string","maxLength":500,"minLength":1},"type":"array","maxItems":100,"title":"Company Names","description":"The company names value for this prospectingtarget.","examples":[["Example company names"]]},"company_domains":{"items":{"type":"string","maxLength":253,"minLength":1},"type":"array","maxItems":100,"title":"Company Domains","description":"The company domains value for this prospectingtarget.","examples":[["Example company domains"]]},"job_titles":{"items":{"type":"string","maxLength":500,"minLength":1},"type":"array","maxItems":100,"title":"Job Titles","description":"The job titles value for this prospectingtarget.","examples":[["Example job titles"]]},"seniorities":{"items":{"type":"string","enum":["individual_contributor","manager","director","vp","c_suite","owner","founder"]},"type":"array","maxItems":20,"title":"Seniorities","description":"The seniorities value for this prospectingtarget.","examples":[["individual_contributor"]]},"industries":{"items":{"type":"string","maxLength":500,"minLength":1},"type":"array","maxItems":100,"title":"Industries","description":"The industries value for this prospectingtarget.","examples":[["Example industries"]]},"locations":{"items":{"type":"string","maxLength":500,"minLength":1},"type":"array","maxItems":100,"title":"Locations","description":"The locations value for this prospectingtarget.","examples":[["Example locations"]]},"keywords":{"items":{"type":"string","maxLength":500,"minLength":1},"type":"array","maxItems":100,"title":"Keywords","description":"The keywords value for this prospectingtarget.","examples":[["Example keywords"]]},"company_headcount":{"anyOf":[{"$ref":"#/components/schemas/CompanyHeadcount"},{"type":"null"}],"description":"The company headcount value for this prospectingtarget.","examples":[{}]},"country_code":{"anyOf":[{"$ref":"#/components/schemas/CountryCode"},{"type":"null"}],"description":"The country code value for this prospectingtarget.","examples":["AD"]}},"additionalProperties":false,"type":"object","title":"ProspectingTarget","description":"Structured prospectingtarget data exposed by the public API.","examples":[{}]},"PublicAccountResearchIn":{"properties":{"domain":{"type":"string","maxLength":253,"minLength":1,"title":"Domain","description":"Company domain to research. Bare domains resolve best (`hubspot.com`); schemes, `www.` and paths are stripped automatically.","examples":["hubspot.com"]},"analyze":{"type":"boolean","title":"Analyze","description":"When no record exists yet, fetch and analyze the company's website on demand, then return the structured record. The analysis is metered as one extra `prospect_research` request; the result carries `analyzed: true`. Websites that cannot be fetched return `422 account_unanalyzable`.","default":false,"examples":[true]},"include_similar":{"type":"boolean","title":"Include Similar","description":"Enrich the result with up to 10 lookalike companies from the similarity index (`similar_companies`). Similars enrich a result; they never fail the lookup.","default":false,"examples":[true]}},"additionalProperties":false,"type":"object","required":["domain"],"title":"PublicAccountResearchIn","description":"Request one structured research record for a company domain.","examples":[{"analyze":true,"domain":"hubspot.com","include_similar":true}]},"PublicAudienceCompany":{"properties":{"result_shape":{"type":"string","const":"company","title":"Result Shape","description":"Discriminator indicating a company row with nested contacts.","examples":["company"]},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name","description":"Company name; null when unavailable.","examples":["Acme Corporation"]},"company_domain":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"hostname","title":"Company Domain","description":"Company domain; null when unavailable.","examples":["acme.example"]},"company_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Description","description":"Company description; null when unavailable.","examples":["Enterprise B2B SaaS company."]},"employee_count":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Employee Count","description":"Employee-count range; null when unavailable.","examples":["501-1000"]},"primary_industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Industry","description":"Primary industry; null when unavailable.","examples":["Software"]},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City","description":"Company city; null when unavailable.","examples":["Austin"]},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State","description":"Company state or region; null when unavailable.","examples":["TX"]},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"Company country; null when unavailable.","examples":["United States"]},"intent_topics_matched":{"items":{"type":"string"},"type":"array","title":"Intent Topics Matched","description":"Always-present matched intent topics.","examples":[["revenue operations"]]},"prelim_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Prelim Score","description":"Preliminary company score; null when unavailable.","examples":[88.0]},"deep_match_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Deep Match Score","description":"Deep match score; null when unavailable.","examples":[90.0]},"final_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Final Score","description":"Overall company score; null when unavailable.","examples":[91.5]},"company_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Company Score","description":"Company-fit score; null when unavailable.","examples":[91.0]},"readiness_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Readiness Score","description":"Buying-readiness score; null when unavailable.","examples":[87.0]},"contact_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Contact Score","description":"Aggregate contact score; null when unavailable.","examples":[92.0]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Generated reason for the company score; null when unavailable.","examples":["Strong ICP and intent match."]},"contact_strategy":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact Strategy","description":"Recommended contact strategy; null when unavailable.","examples":["Lead with the primary contact."]},"playbook_url":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"uri","title":"Playbook Url","description":"Optional generated Playbook URL for the company.","examples":[null]},"contacts":{"items":{"$ref":"#/components/schemas/PublicAudienceContact"},"type":"array","title":"Contacts","description":"Always-present contact rows nested under this company.","examples":[[{"business_email":"jordan.reyes@acme.example","city":"Austin","contact_id":5012,"country":"United States","final_score":91.5,"fit_score":92.0,"full_name":"Jordan Reyes","is_primary":true,"job_title":"VP Revenue Operations","linkedin_url":"https://www.linkedin.com/in/jordan-reyes","reason":"Owns the workflow the offer improves.","reliability_score":90.0,"state":"TX","validity_score":95.0}]]}},"type":"object","required":["result_shape"],"title":"PublicAudienceCompany","description":"A company-shaped Audience candidate with nested contacts.","examples":[{"city":"Austin","company_description":"Enterprise B2B SaaS company.","company_domain":"acme.example","company_name":"Acme Corporation","company_score":91.0,"contact_score":92.0,"contact_strategy":"Lead with the primary contact.","contacts":[{"business_email":"jordan.reyes@acme.example","city":"Austin","contact_id":5012,"country":"United States","final_score":91.5,"fit_score":92.0,"full_name":"Jordan Reyes","is_primary":true,"job_title":"VP Revenue Operations","linkedin_url":"https://www.linkedin.com/in/jordan-reyes","reason":"Owns the workflow the offer improves.","reliability_score":90.0,"state":"TX","validity_score":95.0}],"country":"United States","deep_match_score":90.0,"employee_count":"501-1000","final_score":91.5,"intent_topics_matched":["revenue operations"],"prelim_score":88.0,"primary_industry":"Software","readiness_score":87.0,"reason":"Strong ICP and intent match.","result_shape":"company","state":"TX"}]},"PublicAudienceContact":{"properties":{"contact_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Contact Id","description":"Opaque source contact identifier; null when unavailable.","examples":[5012]},"full_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Full Name","description":"Contact full name; null when unavailable.","examples":["Jordan Reyes"]},"job_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Title","description":"Contact job title; null when unavailable.","examples":["VP Revenue Operations"]},"business_email":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"email","title":"Business Email","description":"Business email; null when unavailable.","examples":["jordan.reyes@acme.example"]},"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"uri","title":"Linkedin Url","description":"LinkedIn profile URL; null when unavailable.","examples":["https://www.linkedin.com/in/jordan-reyes"]},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City","description":"Contact city; null when unavailable.","examples":["Austin"]},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State","description":"Contact state or region; null when unavailable.","examples":["TX"]},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"Contact country; null when unavailable.","examples":["United States"]},"final_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Final Score","description":"Overall contact score from 0 to 100; null when unavailable.","examples":[91.5]},"validity_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Validity Score","description":"Contact-validity score from 0 to 100; null when unavailable.","examples":[95.0]},"reliability_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Reliability Score","description":"Contact-reliability score from 0 to 100; null when unavailable.","examples":[90.0]},"fit_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Fit Score","description":"Contact-fit score from 0 to 100; null when unavailable.","examples":[92.0]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Generated reason for the contact score; null when unavailable.","examples":["Owns the workflow the offer improves."]},"is_primary":{"type":"boolean","title":"Is Primary","description":"Whether this is the recommended first contact at the company.","default":false,"examples":[true]},"playbook_url":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"uri","title":"Playbook Url","description":"Optional generated Playbook URL for this contact.","examples":[null]}},"type":"object","title":"PublicAudienceContact","description":"A contact nested under a company-shaped Audience candidate.","examples":[{"business_email":"jordan.reyes@acme.example","city":"Austin","contact_id":5012,"country":"United States","final_score":91.5,"fit_score":92.0,"full_name":"Jordan Reyes","is_primary":true,"job_title":"VP Revenue Operations","linkedin_url":"https://www.linkedin.com/in/jordan-reyes","reason":"Owns the workflow the offer improves.","reliability_score":90.0,"state":"TX","validity_score":95.0}]},"PublicAudienceContactCandidate":{"properties":{"contact_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Contact Id","description":"Opaque source contact identifier; null when unavailable.","examples":[5012]},"full_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Full Name","description":"Contact full name; null when unavailable.","examples":["Jordan Reyes"]},"job_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Title","description":"Contact job title; null when unavailable.","examples":["VP Revenue Operations"]},"business_email":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"email","title":"Business Email","description":"Business email; null when unavailable.","examples":["jordan.reyes@acme.example"]},"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"uri","title":"Linkedin Url","description":"LinkedIn profile URL; null when unavailable.","examples":["https://www.linkedin.com/in/jordan-reyes"]},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City","description":"Contact city; null when unavailable.","examples":["Austin"]},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State","description":"Contact state or region; null when unavailable.","examples":["TX"]},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"Contact country; null when unavailable.","examples":["United States"]},"final_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Final Score","description":"Overall contact score from 0 to 100; null when unavailable.","examples":[91.5]},"validity_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Validity Score","description":"Contact-validity score from 0 to 100; null when unavailable.","examples":[95.0]},"reliability_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Reliability Score","description":"Contact-reliability score from 0 to 100; null when unavailable.","examples":[90.0]},"fit_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Fit Score","description":"Contact-fit score from 0 to 100; null when unavailable.","examples":[92.0]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Generated reason for the contact score; null when unavailable.","examples":["Owns the workflow the offer improves."]},"is_primary":{"type":"boolean","title":"Is Primary","description":"Whether this is the recommended first contact at the company.","default":false,"examples":[true]},"playbook_url":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"uri","title":"Playbook Url","description":"Optional generated Playbook URL for this contact.","examples":[null]},"result_shape":{"type":"string","const":"contact","title":"Result Shape","description":"Discriminator indicating a flat contact row.","examples":["contact"]},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name","description":"Contact company name; null when unavailable.","examples":["Acme Corporation"]},"company_domain":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"hostname","title":"Company Domain","description":"Contact company domain; null when unavailable.","examples":["acme.example"]},"primary_industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Industry","description":"Contact company industry; null when unavailable.","examples":["Software"]},"intent_topics_matched":{"items":{"type":"string"},"type":"array","title":"Intent Topics Matched","description":"Always-present matched intent topics.","examples":[["revenue operations"]]},"prelim_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Prelim Score","description":"Preliminary contact score; null when unavailable.","examples":[88.0]}},"type":"object","required":["result_shape"],"title":"PublicAudienceContactCandidate","description":"A flat contact-shaped Audience candidate.","examples":[{"business_email":"jordan.reyes@acme.example","city":"Austin","company_domain":"acme.example","company_name":"Acme Corporation","contact_id":5012,"country":"United States","final_score":91.5,"fit_score":92.0,"full_name":"Jordan Reyes","intent_topics_matched":["revenue operations"],"is_primary":true,"job_title":"VP Revenue Operations","linkedin_url":"https://www.linkedin.com/in/jordan-reyes","prelim_score":88.0,"primary_industry":"Software","reason":"Owns the workflow the offer improves.","reliability_score":90.0,"result_shape":"contact","state":"TX","validity_score":95.0}]},"PublicAudienceIcp":{"properties":{"offer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Offer","description":"Offer summarized by the ICP.","examples":["Northstar Analytics"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Generated ICP description.","examples":["Enterprise B2B SaaS companies with complex revenue operations."]},"intent_topics":{"items":{"type":"string"},"type":"array","title":"Intent Topics","description":"Always-present ICP intent topics.","examples":[["revenue operations"]]},"industries":{"items":{"type":"string"},"type":"array","title":"Industries","description":"Always-present ICP industries.","examples":[["Software"]]},"job_titles":{"items":{"type":"string"},"type":"array","title":"Job Titles","description":"Always-present ICP job titles.","examples":[["VP Revenue Operations"]]}},"type":"object","title":"PublicAudienceIcp","description":"The compact ideal-customer-profile summary stored with an Audience job.","examples":[{"description":"Enterprise B2B SaaS companies with complex revenue operations.","industries":["Software"],"intent_topics":["revenue operations"],"job_titles":["VP Revenue Operations"],"offer":"Northstar Analytics"}]},"PublicAudienceIndustryCount":{"properties":{"industry":{"type":"string","title":"Industry","description":"Industry name.","examples":["Software"]},"count":{"type":"integer","minimum":0.0,"title":"Count","description":"Candidates in this industry.","examples":[64]}},"type":"object","required":["industry","count"],"title":"PublicAudienceIndustryCount","description":"One industry count in an Audience result summary.","examples":[{"count":64,"industry":"Software"}]},"PublicAudienceJobInput":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Saved campaign name; null when omitted.","examples":["North America RevOps leaders"]},"objective":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Objective","description":"Audience objective; null only for legacy sparse jobs.","examples":["Find VP Revenue Operations leaders at B2B SaaS companies."]},"website_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website Url","description":"Seller website domain; null when omitted.","examples":["northstar.example"]},"product_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Product Name","description":"Seller product name; null when omitted.","examples":["Northstar Analytics"]},"product_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Product Description","description":"Seller product description; null when omitted.","examples":["Revenue-intelligence software."]},"icp_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Icp Description","description":"ICP guidance; null when omitted.","examples":["Enterprise B2B SaaS companies."]},"additional_context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Additional Context","description":"Additional targeting context; null when omitted.","examples":["Prioritize North America."]},"b2b":{"type":"boolean","title":"B2B","description":"Whether the targeting request is B2B.","default":true,"examples":[true]},"skip_intent":{"type":"boolean","title":"Skip Intent","description":"Whether intent discovery was skipped.","default":false,"examples":[false]},"target_size":{"type":"integer","maximum":2000.0,"minimum":1.0,"title":"Target Size","description":"Requested candidate count retained with the job.","default":100,"examples":[100]},"max_contacts_per_company":{"type":"integer","maximum":10.0,"minimum":1.0,"title":"Max Contacts Per Company","description":"Requested contacts per company.","default":3,"examples":[3]},"excluded_domains":{"items":{"type":"string"},"type":"array","title":"Excluded Domains","description":"Always-present excluded company domains.","examples":[["existing-customer.example"]]},"playbooks_enabled":{"type":"boolean","title":"Playbooks Enabled","description":"Whether candidate Playbooks were requested.","default":false,"examples":[false]},"model":{"type":"string","enum":["default"],"const":"default","title":"Model","description":"Audience-generation model retained with the job.","default":"default","examples":["default"]}},"type":"object","title":"PublicAudienceJobInput","description":"Typed Audience input snapshot retained with a job.\n\nNew job creation uses `AudienceInput`, which requires `objective`. It is\nnullable here only for retained jobs created before the public contract was\nfully validated.","examples":[{"max_contacts_per_company":3,"model":"default","objective":"Find VP Revenue Operations leaders at B2B SaaS companies.","target_size":100}]},"PublicAudienceJobResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Stable asynchronous job identifier.","examples":["job_playbook_123"]},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"],"title":"Status","description":"Current job state.","examples":["succeeded"]},"progress":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Progress","description":"Coarse completion percentage. Terminal successful jobs report 100.","examples":[100]},"project_id":{"type":"string","title":"Project Id","description":"Project that owns the job and its usage.","examples":["proj_123"]},"campaign_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Campaign Id","description":"Owning Audience campaign; null for Playbooks jobs.","examples":["camp_123"]},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Stable human-readable job failure message; null unless the job failed.","examples":[null]},"error_code":{"anyOf":[{"$ref":"#/components/schemas/PublicErrorCode"},{"type":"null"}],"description":"Stable machine-readable public failure code when one applies; null otherwise.","examples":["insufficient_credits"]},"usage":{"$ref":"#/components/schemas/PublicJobUsage","description":"Usage attributed to this job.","examples":[{"backend_requests":1,"backend_runtime_ms":1830,"cache_write_tokens":300,"cached_input_tokens":1200,"cost_usd":0.0123,"input_tokens":3500,"output_tokens":700,"reasoning_tokens":180,"tokens":4200}]},"stages":{"anyOf":[{"items":{"$ref":"#/components/schemas/PublicJobStage"},"type":"array"},{"type":"null"}],"title":"Stages","description":"Ordered Audience stages; null for Playbooks jobs.","examples":[[{"key":"prelim","label":"Preliminary scoring","status":"completed"}]]},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the server accepted the job.","examples":["2026-07-13T12:00:00Z"]},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"When the job input and result leave the 30-day public retention window.","examples":["2026-08-12T12:00:00Z"]},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"When execution began; null while queued.","examples":["2026-07-13T12:00:00Z"]},"finished_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Finished At","description":"When execution reached a terminal state; null while active.","examples":["2026-07-13T12:00:00Z"]},"type":{"type":"string","const":"audiences","title":"Type","description":"Discriminator selecting the Audiences input and result shapes.","examples":["audiences"]},"input":{"$ref":"#/components/schemas/PublicAudienceJobInput","description":"Typed Audience request snapshot retained with the job.","examples":[{"max_contacts_per_company":3,"model":"default","objective":"Find VP Revenue Operations leaders at B2B SaaS companies.","target_size":100}]},"result":{"anyOf":[{"$ref":"#/components/schemas/PublicAudienceResult"},{"type":"null"}],"description":"Compact typed Audience result; null until the job succeeds.","examples":[{"avg_final_score":84.2,"contacts_count":230,"count":100,"generated_at":"2026-07-13T12:00:00Z","icp":{"description":"Enterprise B2B SaaS companies with complex revenue operations.","industries":["Software"],"intent_topics":["revenue operations"],"job_titles":["VP Revenue Operations"],"offer":"Northstar Analytics"},"max_final_score":96.0,"result_shape":"company","rtsa_cycle_id":"cycle_123","top_industries":[{"count":64,"industry":"Software"}]}]}},"type":"object","required":["id","status","progress","project_id","usage","created_at","expires_at","type","input"],"title":"PublicAudienceJobResponse","description":"An Audiences-specific asynchronous job response.","examples":[{"campaign_id":"camp_123","created_at":"2026-07-13T12:00:00Z","expires_at":"2026-08-12T12:00:00Z","finished_at":"2026-07-13T12:00:00Z","id":"job_audience_123","input":{"max_contacts_per_company":3,"model":"default","objective":"Find VP Revenue Operations leaders at B2B SaaS companies.","target_size":100},"progress":100,"project_id":"proj_123","result":{"avg_final_score":84.2,"contacts_count":230,"count":100,"generated_at":"2026-07-13T12:00:00Z","icp":{"description":"Enterprise B2B SaaS companies with complex revenue operations.","industries":["Software"],"intent_topics":["revenue operations"],"job_titles":["VP Revenue Operations"],"offer":"Northstar Analytics"},"max_final_score":96.0,"result_shape":"company","rtsa_cycle_id":"cycle_123","top_industries":[{"count":64,"industry":"Software"}]},"stages":[{"key":"icp","label":"Ideal customer profile","status":"completed"}],"started_at":"2026-07-13T12:00:00Z","status":"succeeded","type":"audiences","usage":{"backend_requests":1,"backend_runtime_ms":1830,"cache_write_tokens":300,"cached_input_tokens":1200,"candidates":100,"cost_usd":0.0123,"input_tokens":3500,"output_tokens":700,"reasoning_tokens":180,"tokens":4200}}]},"PublicAudienceResult":{"properties":{"count":{"type":"integer","minimum":0.0,"title":"Count","description":"Total candidates generated by the cycle.","examples":[100]},"result_shape":{"type":"string","enum":["company","contact"],"title":"Result Shape","description":"Whether the candidate endpoint returns company or flat-contact rows.","examples":["company"]},"generated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Generated At","description":"Backend generation timestamp; null when unavailable.","examples":["2026-07-13T12:00:00Z"]},"rtsa_cycle_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rtsa Cycle Id","description":"Opaque upstream cycle identifier; null when unavailable.","examples":["cycle_123"]},"contacts_count":{"type":"integer","minimum":0.0,"title":"Contacts Count","description":"Contacts represented by the generated candidates.","examples":[230]},"avg_final_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Avg Final Score","description":"Average final candidate score; null when no candidate has a score.","examples":[84.2]},"max_final_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Max Final Score","description":"Maximum final candidate score; null when no candidate has a score.","examples":[96.0]},"top_industries":{"items":{"$ref":"#/components/schemas/PublicAudienceIndustryCount"},"type":"array","title":"Top Industries","description":"Always-present top industries by candidate count.","examples":[[{"count":64,"industry":"Software"}]]},"icp":{"anyOf":[{"$ref":"#/components/schemas/PublicAudienceIcp"},{"type":"null"}],"description":"Compact ICP artifact; null while unavailable.","examples":[{"description":"Enterprise B2B SaaS companies with complex revenue operations.","industries":["Software"],"intent_topics":["revenue operations"],"job_titles":["VP Revenue Operations"],"offer":"Northstar Analytics"}]}},"type":"object","required":["count","result_shape","contacts_count"],"title":"PublicAudienceResult","description":"Typed compact result of a successful Audiences job.\n\nFull candidate records are not embedded here; retrieve them through the\npaginated Audience Candidates endpoint.","examples":[{"avg_final_score":84.2,"contacts_count":230,"count":100,"generated_at":"2026-07-13T12:00:00Z","icp":{"description":"Enterprise B2B SaaS companies with complex revenue operations.","industries":["Software"],"intent_topics":["revenue operations"],"job_titles":["VP Revenue Operations"],"offer":"Northstar Analytics"},"max_final_score":96.0,"result_shape":"company","rtsa_cycle_id":"cycle_123","top_industries":[{"count":64,"industry":"Software"}]}]},"PublicBrand":{"properties":{"id":{"type":"string","title":"Id","description":"Stable organization-scoped brand-profile identifier.","examples":["brand_01h8z3m2q7"]},"name":{"type":"string","title":"Name","description":"Current researched or caller-supplied brand name.","examples":["Acme Corporation"]},"key":{"type":"string","title":"Key","description":"Stable human-readable key unique within the organization.","examples":["acme_corporation"]},"company_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Url","description":"Verified or caller-supplied official website; null until resolved.","examples":["https://acme.example"]},"extraction_status":{"type":"string","title":"Extraction Status","description":"Legacy-compatible profile extraction state.","examples":["ready"]},"research_status":{"type":"string","enum":["not_started","queued","researching","ready","failed","canceled"],"title":"Research Status","description":"State of the latest brand-guideline research attempt.","examples":["ready"]},"research_job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Research Job Id","description":"Latest Brands job ID; null before research starts.","examples":["job_brand_123"]},"research_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Research Error","description":"Safe failure summary; null unless the latest attempt failed.","examples":[null]},"guideline_available":{"type":"boolean","title":"Guideline Available","description":"Whether a valid standardized guideline can be read.","examples":[true]},"guideline_revision":{"type":"integer","minimum":0.0,"title":"Guideline Revision","description":"Monotonic successful guideline revision; zero before the first success.","examples":[1]},"source_count":{"type":"integer","minimum":0.0,"title":"Source Count","description":"Number of provenance sources retained for the current guideline.","examples":[8]},"is_default":{"type":"boolean","title":"Is Default","description":"Whether this is the organization's default generation brand.","examples":[true]},"archived":{"type":"boolean","title":"Archived","description":"Whether the profile is archived and excluded from active lists.","examples":[false]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When the brand profile was created.","examples":["2026-07-13T12:00:00Z"]},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At","description":"When the brand profile or research state last changed.","examples":["2026-07-13T12:00:00Z"]}},"type":"object","required":["id","name","key","extraction_status","research_status","guideline_available","guideline_revision","source_count","is_default","archived"],"title":"PublicBrand","description":"A public Brand resource and the state of its latest research run.","examples":[{"archived":false,"company_url":"https://acme.example","created_at":"2026-07-13T12:00:00Z","extraction_status":"ready","guideline_available":true,"guideline_revision":1,"id":"brand_01h8z3m2q7","is_default":true,"key":"acme_corporation","name":"Acme Corporation","research_job_id":"job_brand_123","research_status":"ready","source_count":8,"updated_at":"2026-07-13T12:00:00Z"}]},"PublicBrandCreateIn":{"properties":{"company_name":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}],"title":"Company Name","description":"Company or brand name. Required when website_url is omitted.","examples":["Acme Corporation"]},"website_url":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Website Url","description":"Candidate official website. Required when company_name is omitted.","examples":["https://acme.example"]},"key":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Key","description":"Optional organization-unique stable key; generated from the resolved name when omitted.","examples":["acme_corporation"]},"is_default":{"type":"boolean","title":"Is Default","description":"Make this the organization's default generation brand.","default":false,"examples":[false]}},"additionalProperties":false,"type":"object","title":"PublicBrandCreateIn","description":"Identity seed for a new asynchronous brand-research run.","examples":[{"company_name":"Acme Corporation","is_default":false,"key":"acme_corporation","website_url":"https://acme.example"}]},"PublicBrandJobResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Stable asynchronous job identifier.","examples":["job_playbook_123"]},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"],"title":"Status","description":"Current job state.","examples":["succeeded"]},"progress":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Progress","description":"Coarse completion percentage. Terminal successful jobs report 100.","examples":[100]},"project_id":{"type":"string","title":"Project Id","description":"Project that owns the job and its usage.","examples":["proj_123"]},"campaign_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Campaign Id","description":"Owning Audience campaign; null for Playbooks jobs.","examples":["camp_123"]},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Stable human-readable job failure message; null unless the job failed.","examples":[null]},"error_code":{"anyOf":[{"$ref":"#/components/schemas/PublicErrorCode"},{"type":"null"}],"description":"Stable machine-readable public failure code when one applies; null otherwise.","examples":["insufficient_credits"]},"usage":{"$ref":"#/components/schemas/PublicJobUsage","description":"Usage attributed to this job.","examples":[{"backend_requests":1,"backend_runtime_ms":1830,"cache_write_tokens":300,"cached_input_tokens":1200,"cost_usd":0.0123,"input_tokens":3500,"output_tokens":700,"reasoning_tokens":180,"tokens":4200}]},"stages":{"anyOf":[{"items":{"$ref":"#/components/schemas/PublicJobStage"},"type":"array"},{"type":"null"}],"title":"Stages","description":"Ordered Audience stages; null for Playbooks jobs.","examples":[[{"key":"prelim","label":"Preliminary scoring","status":"completed"}]]},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the server accepted the job.","examples":["2026-07-13T12:00:00Z"]},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"When the job input and result leave the 30-day public retention window.","examples":["2026-08-12T12:00:00Z"]},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"When execution began; null while queued.","examples":["2026-07-13T12:00:00Z"]},"finished_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Finished At","description":"When execution reached a terminal state; null while active.","examples":["2026-07-13T12:00:00Z"]},"type":{"type":"string","const":"brands","title":"Type","description":"Discriminator selecting the Brands input and result shapes.","examples":["brands"]},"input":{"$ref":"#/components/schemas/PublicBrandResearchJobInput","description":"Typed research input retained with the job.","examples":[{"brand_profile_id":"brand_01h8z3m2q7","company_name":"Acme Corporation","company_name_supplied":true,"website_url":"https://acme.example"}]},"result":{"anyOf":[{"$ref":"#/components/schemas/PublicBrandResearchResult"},{"type":"null"}],"description":"Guideline pointer and integrity metadata; null until the job succeeds.","examples":[{"brand_profile_id":"brand_01h8z3m2q7","guideline_hash":"9b5de1c78bd1d21b6168cf6b73e186dcf9a875606a0e81025fcb8015e089f9f1","guideline_path":"/v1/brands/brand_01h8z3m2q7/guideline","revision":1,"schema_version":"2026-07-16","source_count":8}]}},"type":"object","required":["id","status","progress","project_id","usage","created_at","expires_at","type","input"],"title":"PublicBrandJobResponse","description":"A Brands-specific asynchronous web-research job response.","examples":[{"created_at":"2026-07-13T12:00:00Z","expires_at":"2026-08-12T12:00:00Z","finished_at":"2026-07-13T12:00:00Z","id":"job_brand_123","input":{"brand_profile_id":"brand_01h8z3m2q7","company_name":"Acme Corporation","company_name_supplied":true,"website_url":"https://acme.example"},"progress":100,"project_id":"proj_123","result":{"brand_profile_id":"brand_01h8z3m2q7","guideline_hash":"9b5de1c78bd1d21b6168cf6b73e186dcf9a875606a0e81025fcb8015e089f9f1","guideline_path":"/v1/brands/brand_01h8z3m2q7/guideline","revision":1,"schema_version":"2026-07-16","source_count":8},"started_at":"2026-07-13T12:00:00Z","status":"succeeded","type":"brands","usage":{"backend_requests":6,"backend_runtime_ms":1830,"cache_write_tokens":300,"cached_input_tokens":1200,"cost_usd":0.0123,"input_tokens":3500,"output_tokens":700,"reasoning_tokens":180,"tokens":8400}}]},"PublicBrandResearchJobInput":{"properties":{"brand_profile_id":{"type":"string","title":"Brand Profile Id","description":"Brand profile created or refreshed by this run.","examples":["brand_01h8z3m2q7"]},"company_name":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}],"title":"Company Name","description":"Company name supplied to or retained by the researcher.","examples":["Acme Corporation"]},"website_url":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Website Url","description":"Candidate official website; the researcher verifies it.","examples":["https://acme.example"]},"company_name_supplied":{"type":"boolean","title":"Company Name Supplied","description":"Whether the caller supplied the company name rather than the platform deriving it.","default":false,"examples":[true]}},"additionalProperties":false,"type":"object","required":["brand_profile_id"],"title":"PublicBrandResearchJobInput","description":"Retained input for an asynchronous brand-guideline research run.","examples":[{"brand_profile_id":"brand_01h8z3m2q7","company_name":"Acme Corporation","company_name_supplied":true,"website_url":"https://acme.example"}]},"PublicBrandResearchResult":{"properties":{"brand_profile_id":{"type":"string","title":"Brand Profile Id","description":"Brand profile whose guideline was written.","examples":["brand_01h8z3m2q7"]},"schema_version":{"type":"string","title":"Schema Version","description":"Canonical guideline schema version.","examples":["2026-07-16"]},"revision":{"type":"integer","minimum":1.0,"title":"Revision","description":"Monotonic successful guideline revision.","examples":[1]},"guideline_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Guideline Hash","description":"SHA-256 of the canonical guideline snapshot.","examples":["9b5de1c78bd1d21b6168cf6b73e186dcf9a875606a0e81025fcb8015e089f9f1"]},"source_count":{"type":"integer","minimum":0.0,"title":"Source Count","description":"Number of retained provenance sources.","examples":[8]},"guideline_path":{"type":"string","title":"Guideline Path","description":"Public path for reading the completed guideline.","examples":["/v1/brands/brand_01h8z3m2q7/guideline"]}},"type":"object","required":["brand_profile_id","schema_version","revision","guideline_hash","source_count","guideline_path"],"title":"PublicBrandResearchResult","description":"Pointer and integrity metadata for a completed brand guideline.","examples":[{"brand_profile_id":"brand_01h8z3m2q7","guideline_hash":"9b5de1c78bd1d21b6168cf6b73e186dcf9a875606a0e81025fcb8015e089f9f1","guideline_path":"/v1/brands/brand_01h8z3m2q7/guideline","revision":1,"schema_version":"2026-07-16","source_count":8}]},"PublicBrandsResponse":{"properties":{"brands":{"items":{"$ref":"#/components/schemas/PublicBrand"},"type":"array","title":"Brands","description":"Active brands ordered by default status and name.","examples":[[{"archived":false,"company_url":"https://acme.example","created_at":"2026-07-13T12:00:00Z","extraction_status":"ready","guideline_available":true,"guideline_revision":1,"id":"brand_01h8z3m2q7","is_default":true,"key":"acme_corporation","name":"Acme Corporation","research_job_id":"job_brand_123","research_status":"ready","source_count":8,"updated_at":"2026-07-13T12:00:00Z"}]]}},"type":"object","required":["brands"],"title":"PublicBrandsResponse","description":"All active Brand resources visible to the authenticated organization.","examples":[{"brands":[{"archived":false,"company_url":"https://acme.example","created_at":"2026-07-13T12:00:00Z","extraction_status":"ready","guideline_available":true,"guideline_revision":1,"id":"brand_01h8z3m2q7","is_default":true,"key":"acme_corporation","name":"Acme Corporation","research_job_id":"job_brand_123","research_status":"ready","source_count":8,"updated_at":"2026-07-13T12:00:00Z"}]}]},"PublicBudgetStatus":{"properties":{"period":{"type":"string","const":"month","title":"Period","description":"UTC calendar period used by this budget.","examples":["month"]},"scope":{"type":"string","enum":["organization","project"],"title":"Scope","description":"Tenant scope selected by this budget.","examples":["project"]},"capability_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Capability Key","description":"Capability restriction, or null when all capability spend is included.","examples":[null]},"limit_usd":{"type":"number","minimum":0.0,"title":"Limit Usd","description":"Configured monthly cost ceiling in USD.","examples":[50]},"spend_usd":{"type":"number","minimum":0.0,"title":"Spend Usd","description":"Cost-ledger spend in this budget's complete scope this month.","examples":[1.243]},"remaining_usd":{"type":"number","minimum":0.0,"title":"Remaining Usd","description":"Non-negative budget limit minus current spend.","examples":[48.757]},"hard_limit":{"type":"boolean","title":"Hard Limit","description":"Whether reaching the ceiling rejects new work.","examples":[true]},"resets_at":{"type":"string","format":"date-time","title":"Resets At","description":"UTC boundary at which the monthly budget period resets.","examples":["2026-08-01T00:00:00Z"]}},"type":"object","required":["period","scope","limit_usd","spend_usd","remaining_usd","hard_limit","resets_at"],"title":"PublicBudgetStatus","description":"One monthly cost budget applicable to the authenticated project.","examples":[{"hard_limit":true,"limit_usd":50,"period":"month","remaining_usd":48.757,"resets_at":"2026-08-01T00:00:00Z","scope":"project","spend_usd":1.243}]},"PublicCampaign":{"properties":{"id":{"type":"string","title":"Id","description":"Stable campaign identifier.","examples":["camp_123"]},"project_id":{"type":"string","title":"Project Id","description":"Project that owns the campaign.","examples":["proj_123"]},"name":{"type":"string","maxLength":160,"minLength":1,"title":"Name","description":"Campaign name.","examples":["North America RevOps leaders"]},"input":{"$ref":"#/components/schemas/AudienceInput","description":"Typed Audience specification saved for future cycles.","examples":[{"excluded_domains":["existing-customer.example"],"max_contacts_per_company":3,"model":"default","name":"North America RevOps leaders","objective":"Find VP and director-level revenue operations leaders at B2B SaaS companies.","playbooks_enabled":false,"product_description":"Revenue-intelligence software for enterprise sales teams.","product_name":"Northstar Analytics","target_size":100,"website_url":"northstar.example"}]},"setup_ready":{"type":"boolean","title":"Setup Ready","description":"Whether the first cycle has produced reusable ICP, intent, and industry artifacts.","examples":[true]},"cycle_count":{"type":"integer","minimum":0.0,"title":"Cycle Count","description":"Number of cycles created for this campaign.","examples":[2]},"last_cycle_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Cycle Id","description":"Most recent cycle job ID; null before any cycle starts.","examples":["job_audience_123"]},"last_cycle_status":{"anyOf":[{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},{"type":"null"}],"title":"Last Cycle Status","description":"Most recent cycle status; null before any cycle starts.","examples":["succeeded"]},"last_cycle_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Cycle At","description":"Most recent cycle acceptance time; null before any cycle starts.","examples":["2026-07-13T12:00:00Z"]},"total_cost_usd":{"type":"number","minimum":0.0,"title":"Total Cost Usd","description":"All-time downstream cost attributed to this campaign in USD.","examples":[1.243]},"schedule":{"$ref":"#/components/schemas/PublicCampaignSchedule","description":"Recurring-cycle settings.","examples":[{"dedupe":true,"enabled":true,"interval_hours":168,"next_run_at":"2026-07-13T12:00:00Z"}]},"archived":{"type":"boolean","title":"Archived","description":"Whether the campaign is archived and cannot start new cycles.","examples":[false]},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the campaign was created.","examples":["2026-07-13T12:00:00Z"]},"key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key","description":"Stable per-project campaign handle; null when unset.","examples":["mid_market_outbound_pilot"]},"objective":{"type":"string","title":"Objective","description":"What the campaign is trying to achieve.","default":"","examples":["Book 20 discovery meetings this quarter."]},"status":{"type":"string","enum":["draft","active","paused","completed","archived"],"title":"Status","description":"Campaign lifecycle status.","default":"active","examples":["active"]},"brand_profile_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand Profile Id","description":"Brand the campaign sells; null when unset.","examples":["brand_123"]},"offer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Offer Id","description":"Offer the campaign sells; null when unset.","examples":["offer_123"]},"playbook_job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Playbook Job Id","description":"Bound playbook job; null when unset.","examples":["job_playbook_123"]},"message_template_revision_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message Template Revision Id","description":"Bound message-template revision; null when unset.","examples":["msgtpl_123"]},"company_dossier_specification_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Dossier Specification Id","description":"Bound company-dossier specification; null when unset.","examples":["companydossier_123"]},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Caller-defined scalar metadata (up to 24 keys).","examples":[{}]}},"type":"object","required":["id","project_id","name","input","setup_ready","cycle_count","total_cost_usd","schedule","archived","created_at"],"title":"PublicCampaign","description":"A saved Audience targeting configuration and its cycle summary.","examples":[{"archived":false,"created_at":"2026-07-13T12:00:00Z","cycle_count":2,"id":"camp_123","input":{"max_contacts_per_company":3,"model":"default","objective":"Find VP Revenue Operations leaders at B2B SaaS companies.","target_size":100},"last_cycle_at":"2026-07-13T12:00:00Z","last_cycle_id":"job_audience_123","last_cycle_status":"succeeded","name":"North America RevOps leaders","project_id":"proj_123","schedule":{"dedupe":true,"enabled":true,"interval_hours":168,"next_run_at":"2026-07-13T12:00:00Z"},"setup_ready":true,"total_cost_usd":1.243}]},"PublicCampaignCreate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":160,"minLength":1},{"type":"null"}],"title":"Name","description":"Optional saved-campaign name. Defaults to a shortened objective when omitted.","examples":["North America RevOps leaders"]},"objective":{"type":"string","maxLength":4000,"minLength":1,"title":"Objective","description":"Required description of the companies and buyers the audience should contain.","examples":["Find VP and director-level revenue operations leaders at B2B SaaS companies."]},"website_url":{"anyOf":[{"type":"string","maxLength":253,"minLength":3,"pattern":"^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"},{"type":"null"}],"format":"hostname","title":"Website Url","description":"Optional seller website domain used as product context.","examples":["northstar.example"]},"product_name":{"anyOf":[{"type":"string","maxLength":160,"minLength":1},{"type":"null"}],"title":"Product Name","description":"Optional product name used to build the ideal customer profile.","examples":["Northstar Analytics"]},"product_description":{"anyOf":[{"type":"string","maxLength":12000,"minLength":1},{"type":"null"}],"title":"Product Description","description":"Optional product description used to refine the ideal customer profile.","examples":["Revenue-intelligence software for enterprise sales teams."]},"icp_description":{"anyOf":[{"type":"string","maxLength":8000,"minLength":1},{"type":"null"}],"title":"Icp Description","description":"Optional pre-existing ideal-customer-profile guidance.","examples":["Enterprise B2B SaaS companies with complex revenue operations."]},"additional_context":{"anyOf":[{"type":"string","maxLength":12000,"minLength":1},{"type":"null"}],"title":"Additional Context","description":"Optional additional targeting context, exclusions, or business constraints.","examples":["Prioritize companies hiring for RevOps in North America."]},"b2b":{"type":"boolean","title":"B2B","description":"Whether the target audience is business-to-business.","default":true,"examples":[true]},"skip_intent":{"type":"boolean","title":"Skip Intent","description":"Skip intent-topic discovery when an existing ICP is sufficient.","default":false,"examples":[false]},"target_size":{"type":"integer","maximum":2000.0,"minimum":1.0,"title":"Target Size","description":"Requested maximum number of audience candidates before server-side plan limits apply.","default":100,"examples":[100]},"max_contacts_per_company":{"type":"integer","maximum":10.0,"minimum":1.0,"title":"Max Contacts Per Company","description":"Maximum contacts returned for each company candidate.","default":3,"examples":[3]},"excluded_domains":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":200,"minItems":1},{"type":"null"}],"title":"Excluded Domains","description":"Company domains excluded from this run. URLs are normalized to domains.","examples":[["existing-customer.example"]]},"playbooks_enabled":{"type":"boolean","title":"Playbooks Enabled","description":"Whether the audience pipeline should generate candidate playbooks when the capability is entitled.","default":false,"examples":[false]},"model":{"type":"string","enum":["default"],"const":"default","title":"Model","description":"Audience-generation model selection. `default` is the currently supported model.","default":"default","examples":["default"]},"key":{"anyOf":[{"type":"string","maxLength":80,"minLength":1},{"type":"null"}],"title":"Key","description":"Stable per-project Campaign handle. Exact normalized key/input replays return the existing Campaign; changed input under the key is rejected.","examples":["Example key"]}},"additionalProperties":false,"type":"object","required":["objective"],"title":"PublicCampaignCreate","description":"Saved targeting input plus the Campaign's stable project-scoped key.","examples":[{"excluded_domains":["existing-customer.example"],"key":"anz_revops_2026q3","max_contacts_per_company":3,"model":"default","name":"North America RevOps leaders","objective":"Find VP and director-level revenue operations leaders at B2B SaaS companies.","playbooks_enabled":false,"product_description":"Revenue-intelligence software for enterprise sales teams.","product_name":"Northstar Analytics","target_size":100,"website_url":"northstar.example"}]},"PublicCampaignSchedule":{"properties":{"enabled":{"type":"boolean","title":"Enabled","description":"Whether recurring cycles are enabled.","examples":[true]},"interval_hours":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Interval Hours","description":"Hours between scheduled cycles; null when scheduling is disabled.","examples":[168]},"dedupe":{"type":"boolean","title":"Dedupe","description":"Whether scheduled runs exclude companies delivered by earlier cycles.","examples":[true]},"next_run_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Next Run At","description":"Next scheduled cycle time; null when no run is scheduled.","examples":["2026-07-13T12:00:00Z"]},"last_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Error","description":"Reason the most recent scheduled run was skipped; null after a successful run.","examples":[null]}},"type":"object","required":["enabled","dedupe"],"title":"PublicCampaignSchedule","description":"Recurring-cycle settings for an Audience campaign.","examples":[{"dedupe":true,"enabled":true,"interval_hours":168,"next_run_at":"2026-07-13T12:00:00Z"}]},"PublicCampaignUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":160,"minLength":1},{"type":"null"}],"title":"Name","description":"Human-readable campaign name.","examples":["Example name"]},"key":{"anyOf":[{"type":"string","maxLength":80,"minLength":1},{"type":"null"}],"title":"Key","description":"Stable per-project handle for agent-built systems.","examples":["Example key"]},"objective":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Objective","description":"What the campaign is trying to achieve.","examples":["Example objective"]},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"draft | active | paused | completed | archived, following the allowed transitions.","examples":["Example status"]},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Up to 24 scalar key/value pairs.","examples":[{}]},"brand_profile_id":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Brand Profile Id","description":"Brand this campaign sells; empty string clears.","examples":["Example brand profile id"]},"offer_id":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Offer Id","description":"Offer this campaign sells; empty string clears.","examples":["Example offer id"]},"playbook_job_id":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Playbook Job Id","description":"Bound playbook job; empty string clears.","examples":["Example playbook job id"]},"message_template_revision_id":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Message Template Revision Id","description":"Bound message template revision; empty string clears.","examples":["Example message template revision id"]},"company_dossier_specification_id":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Company Dossier Specification Id","description":"Bound company dossier specification; empty string clears.","examples":["Example company dossier specification id"]}},"additionalProperties":false,"type":"object","title":"PublicCampaignUpdate","description":"Update the organizing GTM half of a campaign.\n\nEvery field is optional: omit to leave unchanged. For a relation id, send an\nempty string to clear the relation, or a valid id to (re)bind it.","examples":[{}]},"PublicCampaignsResponse":{"properties":{"campaigns":{"items":{"$ref":"#/components/schemas/PublicCampaign"},"type":"array","title":"Campaigns","description":"Campaigns in newest-first order.","examples":[[{"archived":false,"created_at":"2026-07-13T12:00:00Z","cycle_count":2,"id":"camp_123","input":{"max_contacts_per_company":3,"model":"default","objective":"Find VP Revenue Operations leaders at B2B SaaS companies.","target_size":100},"last_cycle_at":"2026-07-13T12:00:00Z","last_cycle_id":"job_audience_123","last_cycle_status":"succeeded","name":"North America RevOps leaders","project_id":"proj_123","schedule":{"dedupe":true,"enabled":true,"interval_hours":168,"next_run_at":"2026-07-13T12:00:00Z"},"setup_ready":true,"total_cost_usd":1.243}]]},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Cursor for the next page; null on the final page.","examples":["50"]},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total campaigns matching the project scope.","examples":[101]}},"type":"object","required":["campaigns","total"],"title":"PublicCampaignsResponse","description":"One cursor page of Audience campaigns.","examples":[{"campaigns":[{"archived":false,"created_at":"2026-07-13T12:00:00Z","cycle_count":2,"id":"camp_123","input":{"max_contacts_per_company":3,"model":"default","objective":"Find VP Revenue Operations leaders at B2B SaaS companies.","target_size":100},"last_cycle_at":"2026-07-13T12:00:00Z","last_cycle_id":"job_audience_123","last_cycle_status":"succeeded","name":"North America RevOps leaders","project_id":"proj_123","schedule":{"dedupe":true,"enabled":true,"interval_hours":168,"next_run_at":"2026-07-13T12:00:00Z"},"setup_ready":true,"total_cost_usd":1.243}],"next_cursor":"50","total":101}]},"PublicCandidatesPage":{"properties":{"job_id":{"type":"string","title":"Job Id","description":"Audience cycle job that produced this page.","examples":["job_audience_123"]},"campaign_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Campaign Id","description":"Owning campaign ID; null for legacy standalone jobs.","examples":["camp_123"]},"count":{"type":"integer","minimum":0.0,"title":"Count","description":"Total candidates produced by the completed cycle.","examples":[100]},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Candidates matching the current query; equals `count` without a filter.","examples":[100]},"candidates":{"items":{"oneOf":[{"$ref":"#/components/schemas/PublicAudienceCompany"},{"$ref":"#/components/schemas/PublicAudienceContactCandidate"}],"discriminator":{"propertyName":"result_shape","mapping":{"company":"#/components/schemas/PublicAudienceCompany","contact":"#/components/schemas/PublicAudienceContactCandidate"}}},"type":"array","title":"Candidates","description":"Candidate rows in the requested page.","examples":[[{"city":"Austin","company_description":"Enterprise B2B SaaS company.","company_domain":"acme.example","company_name":"Acme Corporation","company_score":91.0,"contact_score":92.0,"contact_strategy":"Lead with the primary contact.","contacts":[{"business_email":"jordan.reyes@acme.example","city":"Austin","contact_id":5012,"country":"United States","final_score":91.5,"fit_score":92.0,"full_name":"Jordan Reyes","is_primary":true,"job_title":"VP Revenue Operations","linkedin_url":"https://www.linkedin.com/in/jordan-reyes","reason":"Owns the workflow the offer improves.","reliability_score":90.0,"state":"TX","validity_score":95.0}],"country":"United States","deep_match_score":90.0,"employee_count":"501-1000","final_score":91.5,"intent_topics_matched":["revenue operations"],"prelim_score":88.0,"primary_industry":"Software","readiness_score":87.0,"reason":"Strong ICP and intent match.","result_shape":"company","state":"TX"}]]},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Cursor for the next page; null on the final page.","examples":["50"]}},"type":"object","required":["job_id","count","total","candidates"],"title":"PublicCandidatesPage","description":"One cursor page of typed Audience candidates.","examples":[{"campaign_id":"camp_123","candidates":[{"city":"Austin","company_description":"Enterprise B2B SaaS company.","company_domain":"acme.example","company_name":"Acme Corporation","company_score":91.0,"contact_score":92.0,"contact_strategy":"Lead with the primary contact.","contacts":[{"business_email":"jordan.reyes@acme.example","city":"Austin","contact_id":5012,"country":"United States","final_score":91.5,"fit_score":92.0,"full_name":"Jordan Reyes","is_primary":true,"job_title":"VP Revenue Operations","linkedin_url":"https://www.linkedin.com/in/jordan-reyes","reason":"Owns the workflow the offer improves.","reliability_score":90.0,"state":"TX","validity_score":95.0}],"country":"United States","deep_match_score":90.0,"employee_count":"501-1000","final_score":91.5,"intent_topics_matched":["revenue operations"],"prelim_score":88.0,"primary_industry":"Software","readiness_score":87.0,"reason":"Strong ICP and intent match.","result_shape":"company","state":"TX"}],"count":100,"job_id":"job_audience_123","next_cursor":"50","total":100}]},"PublicCapabilitiesResponse":{"properties":{"capabilities":{"items":{"$ref":"#/components/schemas/PublicCapability"},"type":"array","title":"Capabilities","description":"Enabled capabilities, in catalog order.","examples":[[{"category":"Generation","description":"Generate AI sales playbooks for a target account.","docs_slug":"playbooks","enabled":true,"key":"playbooks","name":"Playbooks","status":"ga"}]]}},"type":"object","required":["capabilities"],"title":"PublicCapabilitiesResponse","description":"The enabled capabilities available to the authenticated project.","examples":[{"capabilities":[{"category":"Generation","description":"Generate AI sales playbooks for a target account.","docs_slug":"playbooks","enabled":true,"key":"playbooks","name":"Playbooks","status":"ga"}]}]},"PublicCapability":{"properties":{"key":{"type":"string","title":"Key","description":"Stable capability key used by API requests and usage rollups.","examples":["playbooks"]},"name":{"type":"string","title":"Name","description":"Human-readable capability name.","examples":["Playbooks"]},"category":{"type":"string","title":"Category","description":"Product category used to group capabilities.","examples":["Generation"]},"status":{"type":"string","enum":["ga","coming_soon"],"title":"Status","description":"Availability status: `ga` is generally available and `coming_soon` is not yet runnable.","examples":["ga"]},"description":{"type":"string","title":"Description","description":"Concise explanation of what the capability does.","examples":["Generate AI sales playbooks for a target account."]},"docs_slug":{"type":"string","title":"Docs Slug","description":"Documentation page slug for this capability.","examples":["playbooks"]},"enabled":{"type":"boolean","title":"Enabled","description":"Whether this organization can use the capability now.","examples":[true]}},"type":"object","required":["key","name","category","status","description","docs_slug","enabled"],"title":"PublicCapability","description":"A capability visible to the API key's organization.","examples":[{"category":"Generation","description":"Generate AI sales playbooks for a target account.","docs_slug":"playbooks","enabled":true,"key":"playbooks","name":"Playbooks","status":"ga"}]},"PublicConnectionOut":{"properties":{"id":{"type":"string","title":"Id","description":"The id value for this publicconnectionout.","examples":["Example id"]},"project_id":{"type":"string","title":"Project Id","description":"The project id value for this publicconnectionout.","examples":["Example project id"]},"provider_key":{"type":"string","title":"Provider Key","description":"The provider key value for this publicconnectionout.","examples":["Example provider key"]},"manifest_version":{"type":"string","title":"Manifest Version","description":"The manifest version value for this publicconnectionout.","examples":["Example manifest version"]},"name":{"type":"string","title":"Name","description":"The name value for this publicconnectionout.","examples":["Example name"]},"configured_fields":{"items":{"type":"string"},"type":"array","title":"Configured Fields","description":"The configured fields value for this publicconnectionout.","examples":[["Example configured fields"]]},"credentials_version":{"type":"integer","title":"Credentials Version","description":"The credentials version value for this publicconnectionout.","examples":[0]},"status":{"type":"string","const":"configured","title":"Status","description":"The status value for this publicconnectionout."},"verification":{"$ref":"#/components/schemas/ConnectionVerificationSummary","description":"The verification value for this publicconnectionout.","examples":[{"mode":"unavailable","status":"unavailable","network_request_made":false}]},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At","description":"The created at value for this publicconnectionout.","examples":["Example created at"]},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At","description":"The updated at value for this publicconnectionout.","examples":["Example updated at"]}},"type":"object","required":["id","project_id","provider_key","manifest_version","name","configured_fields","credentials_version","status","verification","created_at","updated_at"],"title":"PublicConnectionOut","description":"Structured publicconnectionout data exposed by the public API.","examples":[{"id":"Example id","project_id":"Example project id","provider_key":"Example provider key","manifest_version":"Example manifest version","name":"Example name","configured_fields":["Example configured fields"],"credentials_version":0,"status":"configured","verification":{"mode":"unavailable","status":"unavailable","network_request_made":false},"created_at":"Example created at","updated_at":"Example updated at"}]},"PublicConnectionsResponse":{"properties":{"connections":{"items":{"$ref":"#/components/schemas/PublicConnectionOut"},"type":"array","title":"Connections","description":"The connections value for this publicconnectionsresponse.","examples":[[{"id":"Example id","project_id":"Example project id","provider_key":"Example provider key","manifest_version":"Example manifest version","name":"Example name","configured_fields":["Example configured fields"],"credentials_version":0,"status":"configured","verification":{"mode":"unavailable","status":"unavailable","network_request_made":false},"created_at":"Example created at","updated_at":"Example updated at"}]]}},"type":"object","required":["connections"],"title":"PublicConnectionsResponse","description":"Structured publicconnectionsresponse data exposed by the public API.","examples":[{"connections":[{"id":"Example id","project_id":"Example project id","provider_key":"Example provider key","manifest_version":"Example manifest version","name":"Example name","configured_fields":["Example configured fields"],"credentials_version":0,"status":"configured","verification":{"mode":"unavailable","status":"unavailable","network_request_made":false},"created_at":"Example created at","updated_at":"Example updated at"}]}]},"PublicCredits":{"properties":{"billing_enabled":{"type":"boolean","title":"Billing Enabled","description":"Whether the organization uses prepaid usage billing.","examples":[true]},"balance_usd":{"type":"number","title":"Balance Usd","description":"Current prepaid credit balance in USD.","examples":[98.757]},"topup_increment_usd":{"type":"number","exclusiveMinimum":0.0,"title":"Topup Increment Usd","description":"Permitted prepaid top-up increment in USD.","examples":[25.0]}},"type":"object","required":["billing_enabled","balance_usd","topup_increment_usd"],"title":"PublicCredits","description":"Current prepaid-credit context for the organization.","examples":[{"balance_usd":98.757,"billing_enabled":true,"topup_increment_usd":25.0}]},"PublicDocumentJobInput":{"properties":{"brief":{"type":"string","title":"Brief","description":"Caller's brief: the document ask, audience, and key points the agent worked from.","examples":["A first-meeting sales proposal for Acme Corporation's RevOps team: lead with their pipeline-visibility pains, map our onboarding time-to-value, and close with a 90-day rollout plan and pricing summary."]},"document_type":{"anyOf":[{"type":"string","enum":["proposal","playbook","deck","gtm_strategy","report","one_pager"]},{"type":"null"}],"title":"Document Type","description":"Requested collateral type; null when the agent chose the type.","examples":["proposal"]},"format":{"anyOf":[{"type":"string","enum":["pptx","docx","pdf"]},{"type":"null"}],"title":"Format","description":"Requested output file format; null when the agent picked the format.","examples":["docx"]},"target_domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Domain","description":"Normalized bare company domain the agent researched as the document's focus account; null when none was set.","examples":["acme.example"]},"brand":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand","description":"Requested brand profile ID or key; null when the organization default was used.","examples":["northstar"]},"offer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Offer","description":"Resolved key of the offer attached to the run; null when no offer was attached.","examples":["analytics_suite"]},"template_urls":{"items":{"type":"string"},"type":"array","title":"Template Urls","description":"Reference or template document URLs the agent followed for structure, tone and layout (up to three).","examples":[["https://cdn.example/templates/enterprise-proposal.docx"]]},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Caller-supplied document title; null when omitted.","examples":["Acme Corporation proposal"]},"external_ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Ref","description":"Caller-supplied correlation reference; null when omitted.","examples":["crm-account-123"]}},"type":"object","required":["brief"],"title":"PublicDocumentJobInput","description":"Typed Documents input snapshot retained with a job.","examples":[{"brand":"northstar","brief":"A first-meeting sales proposal for Acme Corporation's RevOps team: lead with their pipeline-visibility pains, map our onboarding time-to-value, and close with a 90-day rollout plan and pricing summary.","document_type":"proposal","external_ref":"crm-account-123","format":"docx","offer":"analytics_suite","target_domain":"acme.example","template_urls":["https://cdn.example/templates/enterprise-proposal.docx"],"title":"Acme Corporation proposal"}]},"PublicErrorCode":{"type":"string","enum":["invalid_request","invalid_cursor","brand_profile_mismatch","invalid_campaign_key","invalid_campaign_metadata","invalid_campaign_name","invalid_campaign_objective","invalid_campaign_status","campaign_relation_mismatch","invalid_stage","missing_api_key","invalid_api_key","expired_api_key","authentication_required","insufficient_credits","forbidden","project_archived","capability_disabled","not_found","result_unavailable","brand_not_found","brand_guideline_missing","offer_not_found","playbook_job_not_found","message_template_revision_not_found","company_dossier_specification_not_found","account_coordination_evidence_too_large","account_coordination_idempotency_conflict","account_coordination_policy_not_current","assessment_not_found","audience_empty","audience_idempotency_conflict","audience_member_not_found","audience_not_found","audience_result_changed","audience_review_idempotency_conflict","audience_source_changed","audience_source_unavailable","campaign_not_found","connection_not_found","prospect_not_found","prospecting_job_not_found","prospecting_job_not_ready","prospecting_result_unavailable","playbook_template_not_found","playbook_template_not_ready","job_not_finished","playbooks_document_unavailable","job_expired","not_ready","conflict","idempotency_key_reused","idempotency_in_progress","campaign_archived","campaign_key_exists","invalid_campaign_transition","cycle_in_progress","offer_archived","offer_key_exists","offer_limit_exceeded","invalid_offer_field","invalid_offer_key","invalid_offer_name","invalid_offer_stage","invalid_offer_status","brand_profile_archived","brand_profile_not_found","brand_profile_not_ready","missing_default_brand_profile","outcome_connector_required","outcome_idempotency_conflict","outcome_predates_prospecting_job","outcome_source_mismatch","invalid_insight_group","synthetic_prospect","synthetic_prospecting_result","prospecting_continuation_idempotency_conflict","prospecting_continuation_unavailable","prospecting_parent_changed","prospecting_result_too_large","company_dossier_connection_credentials_changed","company_dossier_connection_incomplete","company_dossier_connection_not_found","company_dossier_connector_manifest_changed","company_dossier_policy_not_current","company_dossier_specification_idempotency_conflict","company_dossier_specification_limit_exceeded","company_dossier_specification_limit_reached","documents_capability_disabled","data_intake_policy_not_current","data_intake_specification_idempotency_conflict","data_intake_specification_limit_exceeded","data_intake_specification_limit_reached","data_intake_specification_not_found","enrichment_member_evidence_invalid","enrichment_members_not_included","enrichment_members_unavailable","enrichment_policy_not_current","enrichment_prerequisites_missing","enrichment_selection_empty","enrichment_selection_too_large","enrichment_specification_idempotency_conflict","enrichment_specification_limit_exceeded","enrichment_specification_limit_reached","enrichment_specification_not_found","message_template_hash_conflict","message_template_key_revision_limit_reached","message_template_body_too_long","message_template_empty_body","message_template_empty_subject","message_template_policy_not_current","message_template_previous_hash_conflict","message_template_revision_idempotency_conflict","message_template_revision_limit_exceeded","message_template_revision_limit_reached","message_template_revision_renderer_unavailable","message_template_revision_sequence_conflict","message_template_required_variables_missing","message_template_subject_too_long","message_template_unknown_variables","message_template_variable_too_long","professional_network_audience_changed","professional_network_audience_source_changed","professional_network_audience_source_invalid","professional_network_audience_source_unavailable","professional_network_capability_disabled","professional_network_connection_incomplete","professional_network_connection_not_found","professional_network_connector_manifest_changed","professional_network_connector_unavailable","professional_network_credentials_changed","professional_network_member_prerequisites_missing","professional_network_members_unavailable","professional_network_policy_not_current","professional_network_selection_empty","professional_network_selection_too_large","professional_network_specification_idempotency_conflict","professional_network_specification_limit_exceeded","professional_network_specification_limit_reached","professional_network_specification_not_found","prospect_research_audience_changed","prospect_research_audience_source_changed","prospect_research_audience_source_invalid","prospect_research_audience_source_unavailable","prospect_research_capability_disabled","prospect_research_member_prerequisites_missing","prospect_research_members_unavailable","prospect_research_policy_not_current","prospect_research_selection_empty","prospect_research_selection_too_large","prospect_research_specification_idempotency_conflict","prospect_research_specification_limit_exceeded","prospect_research_specification_limit_reached","prospect_research_specification_not_found","qualification_policy_idempotency_conflict","qualification_policy_limit_exceeded","qualification_policy_limit_reached","qualification_policy_not_current","qualification_policy_not_found","site_audit_policy_not_current","site_audit_specification_idempotency_conflict","site_audit_specification_limit_exceeded","site_audit_specification_limit_reached","site_audit_specification_not_found","invalid_domain","account_not_found","account_unanalyzable","account_research_not_configured","account_research_unauthorized","account_research_backend_error","account_research_backend_quota","account_research_unavailable","rate_limit_exceeded","quota_exceeded","budget_exceeded","audiences_result_unavailable","audiences_backend_error","audiences_backend_generation_failed","audiences_backend_invalid_response","audiences_backend_timeout","audiences_backend_unavailable","internal_error"],"title":"PublicErrorCode","description":"Finite, machine-readable error codes emitted by the public `/v1` API.","examples":["invalid_request"]},"PublicJobStage":{"properties":{"key":{"type":"string","title":"Key","description":"Stable pipeline stage key.","examples":["prelim"]},"label":{"type":"string","title":"Label","description":"Human-readable stage name.","examples":["Preliminary scoring"]},"status":{"type":"string","enum":["pending","running","completed","skipped","failed"],"title":"Status","description":"Current stage state. A terminal job has no `pending` or `running` stages.","examples":["completed"]}},"type":"object","required":["key","label","status"],"title":"PublicJobStage","description":"One stable stage in a multi-stage asynchronous job.","examples":[{"key":"prelim","label":"Preliminary scoring","status":"completed"}]},"PublicJobUsage":{"properties":{"tokens":{"type":"integer","minimum":0.0,"title":"Tokens","description":"Total input and output tokens reported by the capability.","default":0,"examples":[4200]},"input_tokens":{"type":"integer","minimum":0.0,"title":"Input Tokens","description":"Provider-reported input tokens, including cached and cache-write tokens.","default":0,"examples":[3500]},"cached_input_tokens":{"type":"integer","minimum":0.0,"title":"Cached Input Tokens","description":"Input tokens served from a provider prompt cache; a subset of input_tokens.","default":0,"examples":[1200]},"cache_write_tokens":{"type":"integer","minimum":0.0,"title":"Cache Write Tokens","description":"Input tokens written to a provider prompt cache; a subset of input_tokens.","default":0,"examples":[300]},"output_tokens":{"type":"integer","minimum":0.0,"title":"Output Tokens","description":"Provider-reported output tokens, including reasoning tokens.","default":0,"examples":[700]},"reasoning_tokens":{"type":"integer","minimum":0.0,"title":"Reasoning Tokens","description":"Reasoning tokens included within output_tokens.","default":0,"examples":[180]},"cost_usd":{"type":"number","minimum":0.0,"title":"Cost Usd","description":"Attributed downstream cost in USD.","default":0.0,"examples":[0.0123]},"backend_requests":{"type":"integer","minimum":0.0,"title":"Backend Requests","description":"Number of requests sent to the capability backend.","default":0,"examples":[1]},"backend_runtime_ms":{"type":"integer","minimum":0.0,"title":"Backend Runtime Ms","description":"Measured backend runtime in milliseconds.","default":0,"examples":[1830]},"candidates":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Candidates","description":"Audience candidates produced; null for other job types.","examples":[100]}},"type":"object","title":"PublicJobUsage","description":"Usage attributed to one asynchronous job.\n\nAll numeric counters are always present and start at zero while a job is\nqueued. `candidates` is null for non-Audience jobs.","examples":[{"backend_requests":1,"backend_runtime_ms":1830,"cache_write_tokens":300,"cached_input_tokens":1200,"cost_usd":0.0123,"input_tokens":3500,"output_tokens":700,"reasoning_tokens":180,"tokens":4200}]},"PublicPlaybookCompanyContext":{"properties":{"market_position":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Market Position","description":"Company positioning summary.","examples":["Enterprise revenue-intelligence provider"]},"business_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Business Model","description":"Company business model.","examples":["B2B SaaS"]},"headquarters":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headquarters","description":"Company headquarters.","examples":["San Francisco, CA"]},"employee_count":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Employee Count","description":"Employee-count range when available.","examples":["501-1000"]},"recent_news":{"items":{"type":"string"},"type":"array","title":"Recent News","description":"Always-present recent company developments.","examples":[["Expanded enterprise sales team."]]},"competitors":{"items":{"type":"string"},"type":"array","title":"Competitors","description":"Always-present named competitors.","examples":[["Contoso"]]}},"type":"object","title":"PublicPlaybookCompanyContext","description":"Structured company context included in a Playbook result.","examples":[{"business_model":"B2B SaaS","competitors":["Contoso"],"employee_count":"501-1000","headquarters":"San Francisco, CA","market_position":"Enterprise revenue-intelligence provider","recent_news":["Expanded enterprise sales team."]}]},"PublicPlaybookContactIntelligence":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Contact name.","examples":["Alex Morgan"]},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Contact title.","examples":["VP Revenue Operations"]},"role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Role","description":"Buying-role classification.","examples":["Champion"]},"company":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company","description":"Contact company.","examples":["Acme Corporation"]},"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"uri","title":"Linkedin Url","description":"Optional LinkedIn profile URL.","examples":["https://www.linkedin.com/in/alex-morgan"]},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary","description":"Generated contact summary.","examples":["Owns the workflow this product improves."]},"signals":{"items":{"type":"string"},"type":"array","title":"Signals","description":"Always-present observed contact or company signals.","examples":[["Hiring for RevOps"]]}},"type":"object","title":"PublicPlaybookContactIntelligence","description":"Structured contact context included in a Playbook result.","examples":[{"company":"Acme Corporation","linkedin_url":"https://www.linkedin.com/in/alex-morgan","name":"Alex Morgan","role":"Champion","signals":["Hiring for RevOps"],"summary":"Owns the workflow this product improves.","title":"VP Revenue Operations"}]},"PublicPlaybookConversationStrategy":{"properties":{"opening":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Opening","description":"Suggested opening statement.","examples":["Lead with forecast-quality improvements."]},"approach":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Approach","description":"Suggested account approach.","examples":["Connect operational pain to the planning cycle."]},"key_questions":{"items":{"type":"string"},"type":"array","title":"Key Questions","description":"Always-present discovery questions.","examples":[["Where do forecast handoffs break down today?"]]}},"type":"object","title":"PublicPlaybookConversationStrategy","description":"Suggested conversation plan included in a Playbook result.","examples":[{"approach":"Connect operational pain to the existing planning cycle.","key_questions":["Where do forecast handoffs break down today?"],"opening":"Lead with forecast-quality improvements."}]},"PublicPlaybookIntentAnalysis":{"properties":{"intent_score":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Intent Score","description":"Qualitative intent level when available.","examples":["high"]},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary","description":"Generated intent summary.","examples":["Signals suggest an active evaluation."]},"signals":{"items":{"type":"string"},"type":"array","title":"Signals","description":"Always-present intent signals.","examples":[["Hiring for RevOps"]]},"topics":{"items":{"type":"string"},"type":"array","title":"Topics","description":"Always-present matched intent topics.","examples":[["Revenue operations"]]}},"type":"object","title":"PublicPlaybookIntentAnalysis","description":"Structured intent signals included in a Playbook result.","examples":[{"intent_score":"high","signals":["Hiring for RevOps"],"summary":"Signals suggest an active evaluation.","topics":["Revenue operations"]}]},"PublicPlaybookJobInput":{"properties":{"target_company":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Company","description":"Target company name; null for legacy sparse jobs.","examples":["Acme Corporation"]},"target_company_domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Company Domain","description":"Target company domain; null for legacy sparse jobs.","examples":["acme.example"]},"anchor_company":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Anchor Company","description":"Seller or anchor company; null when omitted.","examples":["Northstar Analytics"]},"product_info":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Product Info","description":"Product context; null when omitted.","examples":["Revenue-intelligence software."]},"tone":{"type":"string","enum":["consultative","direct","technical"],"title":"Tone","description":"Generation tone retained with the job.","default":"consultative","examples":["consultative"]},"sections":{"anyOf":[{"items":{"type":"string","enum":["summary","objective","value_props","sales_angles","personas","services","tech_stack","integrations","objections","meeting_note"]},"type":"array"},{"type":"null"}],"title":"Sections","description":"Requested section subset; null means the complete playbook.","examples":[["summary","personas"]]},"model":{"type":"string","enum":["default"],"const":"default","title":"Model","description":"Generation model retained with the job.","default":"default","examples":["default"]},"brand_profile_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand Profile Id","description":"Selected brand-profile ID; null when omitted.","examples":["brand_01h8z3m2q7"]},"brand_profile_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand Profile Key","description":"Selected brand-profile key; null when omitted.","examples":["northstar"]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stage","description":"Deal stage the playbook targets; null when omitted.","examples":["discovery"]},"playbook_template_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Playbook Template Key","description":"Stage-aware playbook template applied; null when omitted.","examples":["discovery_deep_dive"]},"offer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Offer Id","description":"Offer whose value props seeded the generation context; null when omitted.","examples":["offer_0f47ac10b58cc4372a5670e0"]},"campaign_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Campaign Id","description":"Campaign framing the playbook; null when omitted.","examples":["camp_0f47ac10b58cc4372a5670e0"]}},"type":"object","title":"PublicPlaybookJobInput","description":"Typed Playbooks input snapshot retained with a job.\n\nNew job creation uses `PlaybookInput`, which requires a company name or\ndomain. Fields are nullable here only so older retained jobs created before\nthat contract can still be read safely without inventing request values.","examples":[{"anchor_company":"Northstar Analytics","model":"default","target_company_domain":"acme.example","tone":"consultative"}]},"PublicPlaybookJobResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Stable asynchronous job identifier.","examples":["job_playbook_123"]},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"],"title":"Status","description":"Current job state.","examples":["succeeded"]},"progress":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Progress","description":"Coarse completion percentage. Terminal successful jobs report 100.","examples":[100]},"project_id":{"type":"string","title":"Project Id","description":"Project that owns the job and its usage.","examples":["proj_123"]},"campaign_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Campaign Id","description":"Owning Audience campaign; null for Playbooks jobs.","examples":["camp_123"]},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Stable human-readable job failure message; null unless the job failed.","examples":[null]},"error_code":{"anyOf":[{"$ref":"#/components/schemas/PublicErrorCode"},{"type":"null"}],"description":"Stable machine-readable public failure code when one applies; null otherwise.","examples":["insufficient_credits"]},"usage":{"$ref":"#/components/schemas/PublicJobUsage","description":"Usage attributed to this job.","examples":[{"backend_requests":1,"backend_runtime_ms":1830,"cache_write_tokens":300,"cached_input_tokens":1200,"cost_usd":0.0123,"input_tokens":3500,"output_tokens":700,"reasoning_tokens":180,"tokens":4200}]},"stages":{"anyOf":[{"items":{"$ref":"#/components/schemas/PublicJobStage"},"type":"array"},{"type":"null"}],"title":"Stages","description":"Ordered Audience stages; null for Playbooks jobs.","examples":[[{"key":"prelim","label":"Preliminary scoring","status":"completed"}]]},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the server accepted the job.","examples":["2026-07-13T12:00:00Z"]},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"When the job input and result leave the 30-day public retention window.","examples":["2026-08-12T12:00:00Z"]},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"When execution began; null while queued.","examples":["2026-07-13T12:00:00Z"]},"finished_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Finished At","description":"When execution reached a terminal state; null while active.","examples":["2026-07-13T12:00:00Z"]},"type":{"type":"string","const":"playbooks","title":"Type","description":"Discriminator selecting the Playbooks input and result shapes.","examples":["playbooks"]},"input":{"$ref":"#/components/schemas/PublicPlaybookJobInput","description":"Typed Playbooks request snapshot retained with the job.","examples":[{"anchor_company":"Northstar Analytics","model":"default","target_company_domain":"acme.example","tone":"consultative"}]},"result":{"anyOf":[{"$ref":"#/components/schemas/PublicPlaybookResult"},{"type":"null"}],"description":"Typed Playbooks result; null until the job succeeds.","examples":[{"business_objective":"Improve enterprise pipeline conversion.","business_summary":"Acme sells revenue-intelligence software to enterprise teams.","company_context":{"business_model":"B2B SaaS","competitors":["Contoso"],"employee_count":"501-1000","headquarters":"San Francisco, CA","market_position":"Enterprise revenue-intelligence provider","recent_news":["Expanded enterprise sales team."]},"company_name":"Acme Corporation","contact_intelligence":[{"company":"Acme Corporation","linkedin_url":"https://www.linkedin.com/in/alex-morgan","name":"Alex Morgan","role":"Champion","signals":["Hiring for RevOps"],"summary":"Owns the workflow this product improves.","title":"VP Revenue Operations"}],"contact_overview":"Alex is the recommended first contact.","conversation_strategy":{"approach":"Connect operational pain to the existing planning cycle.","key_questions":["Where do forecast handoffs break down today?"],"opening":"Lead with forecast-quality improvements."},"domain":"acme.example","industry":"Software","intent_analysis":{"intent_score":"high","signals":["Hiring for RevOps"],"summary":"Signals suggest an active evaluation.","topics":["Revenue operations"]},"key_personas":[{"conversation_starters":["Ask about forecast accuracy."],"description":"Owns revenue-process efficiency and forecasting.","name":"Alex Morgan","tags":["economic_buyer"],"title":"VP Revenue Operations"}],"key_services":["Revenue analytics"],"meeting_note_example":"Hi Alex, teams like yours use this to remove forecast blind spots.","potential_objections":[{"objection":"Implementation will take too long.","response":"Start with the existing Salesforce workflow and a focused pilot."}],"product_name":"Northstar Analytics","readiness_level":"active_evaluation","relevant_tech_stack":[{"logo":"https://assets.example/salesforce.svg","name":"Salesforce"}],"risks_and_challenges":{"mitigations":["Offer a focused pilot with measurable outcomes."],"potential_blockers":["Budget timing"],"risks":["Competing internal initiative"]},"sales_angles":["Connect scattered revenue data."],"tech_integration_examples":["Enrich opportunity review workflows."],"tech_integration_questions":["Which Salesforce objects drive forecasting?"],"tech_integration_title":"Salesforce integration","value_props":["Increase forecast confidence."],"website":"https://acme.example"}]}},"type":"object","required":["id","status","progress","project_id","usage","created_at","expires_at","type","input"],"title":"PublicPlaybookJobResponse","description":"A Playbooks-specific asynchronous job response.","examples":[{"created_at":"2026-07-13T12:00:00Z","expires_at":"2026-08-12T12:00:00Z","finished_at":"2026-07-13T12:00:00Z","id":"job_playbook_123","input":{"anchor_company":"Northstar Analytics","model":"default","target_company_domain":"acme.example","tone":"consultative"},"progress":100,"project_id":"proj_123","result":{"business_objective":"Improve enterprise pipeline conversion.","business_summary":"Acme sells revenue-intelligence software to enterprise teams.","company_context":{"business_model":"B2B SaaS","competitors":["Contoso"],"employee_count":"501-1000","headquarters":"San Francisco, CA","market_position":"Enterprise revenue-intelligence provider","recent_news":["Expanded enterprise sales team."]},"company_name":"Acme Corporation","contact_intelligence":[{"company":"Acme Corporation","linkedin_url":"https://www.linkedin.com/in/alex-morgan","name":"Alex Morgan","role":"Champion","signals":["Hiring for RevOps"],"summary":"Owns the workflow this product improves.","title":"VP Revenue Operations"}],"contact_overview":"Alex is the recommended first contact.","conversation_strategy":{"approach":"Connect operational pain to the existing planning cycle.","key_questions":["Where do forecast handoffs break down today?"],"opening":"Lead with forecast-quality improvements."},"domain":"acme.example","industry":"Software","intent_analysis":{"intent_score":"high","signals":["Hiring for RevOps"],"summary":"Signals suggest an active evaluation.","topics":["Revenue operations"]},"key_personas":[{"conversation_starters":["Ask about forecast accuracy."],"description":"Owns revenue-process efficiency and forecasting.","name":"Alex Morgan","tags":["economic_buyer"],"title":"VP Revenue Operations"}],"key_services":["Revenue analytics"],"meeting_note_example":"Hi Alex, teams like yours use this to remove forecast blind spots.","potential_objections":[{"objection":"Implementation will take too long.","response":"Start with the existing Salesforce workflow and a focused pilot."}],"product_name":"Northstar Analytics","readiness_level":"active_evaluation","relevant_tech_stack":[{"logo":"https://assets.example/salesforce.svg","name":"Salesforce"}],"risks_and_challenges":{"mitigations":["Offer a focused pilot with measurable outcomes."],"potential_blockers":["Budget timing"],"risks":["Competing internal initiative"]},"sales_angles":["Connect scattered revenue data."],"tech_integration_examples":["Enrich opportunity review workflows."],"tech_integration_questions":["Which Salesforce objects drive forecasting?"],"tech_integration_title":"Salesforce integration","value_props":["Increase forecast confidence."],"website":"https://acme.example"},"started_at":"2026-07-13T12:00:00Z","status":"succeeded","type":"playbooks","usage":{"backend_requests":1,"backend_runtime_ms":1830,"cache_write_tokens":300,"cached_input_tokens":1200,"cost_usd":0.0123,"input_tokens":3500,"output_tokens":700,"reasoning_tokens":180,"tokens":4200}}]},"PublicPlaybookObjection":{"properties":{"objection":{"type":"string","title":"Objection","description":"Likely buyer objection.","examples":["Implementation will take too long."]},"response":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response","description":"Suggested response; null when no response was generated.","examples":["Start with a focused pilot."]}},"type":"object","required":["objection"],"title":"PublicPlaybookObjection","description":"A likely buyer objection and the suggested response.","examples":[{"objection":"Implementation will take too long.","response":"Start with the existing Salesforce workflow and a focused pilot."}]},"PublicPlaybookPersona":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Persona name when the source identifies one.","examples":["Alex Morgan"]},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Persona job title.","examples":["VP Revenue Operations"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Why this persona matters to the account strategy.","examples":["Owns revenue-process efficiency and forecasting."]},"profile_picture_url":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"uri","title":"Profile Picture Url","description":"Optional profile-image URL supplied by the data source.","examples":["https://assets.example/alex.png"]},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Always-present persona labels.","examples":[["economic_buyer"]]},"conversation_starters":{"items":{"type":"string"},"type":"array","title":"Conversation Starters","description":"Always-present suggested opening topics.","examples":[["Ask about forecast accuracy."]]}},"type":"object","title":"PublicPlaybookPersona","description":"A buyer persona identified in a generated Playbook.","examples":[{"conversation_starters":["Ask about forecast accuracy."],"description":"Owns revenue-process efficiency and forecasting.","name":"Alex Morgan","tags":["economic_buyer"],"title":"VP Revenue Operations"}]},"PublicPlaybookResult":{"properties":{"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name","description":"Target company name.","examples":["Acme Corporation"]},"company_icon_url":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"uri","title":"Company Icon Url","description":"Optional target-company icon URL.","examples":["https://assets.example/acme.png"]},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"hostname","title":"Domain","description":"Target company domain.","examples":["acme.example"]},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"uri","title":"Website","description":"Target company website URL.","examples":["https://acme.example"]},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry","description":"Target company industry.","examples":["Software"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Concise target-company description.","examples":["Enterprise B2B SaaS company."]},"business_summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Business Summary","description":"Generated account summary.","examples":["Acme sells revenue-intelligence software to enterprise teams."]},"business_objective":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Business Objective","description":"Inferred business objective.","examples":["Improve enterprise pipeline conversion."]},"value_props":{"items":{"type":"string"},"type":"array","title":"Value Props","description":"Always-present relevant value propositions.","examples":[["Increase forecast confidence."]]},"sales_angles":{"items":{"type":"string"},"type":"array","title":"Sales Angles","description":"Always-present recommended sales angles.","examples":[["Connect scattered revenue data."]]},"key_personas":{"items":{"$ref":"#/components/schemas/PublicPlaybookPersona"},"type":"array","title":"Key Personas","description":"Always-present prioritized buyer personas.","examples":[[{"conversation_starters":["Ask about forecast accuracy."],"description":"Owns revenue-process efficiency and forecasting.","name":"Alex Morgan","tags":["economic_buyer"],"title":"VP Revenue Operations"}]]},"key_services":{"items":{"type":"string"},"type":"array","title":"Key Services","description":"Always-present relevant services or products.","examples":[["Revenue analytics"]]},"relevant_tech_stack":{"items":{"$ref":"#/components/schemas/PublicPlaybookTechnology"},"type":"array","title":"Relevant Tech Stack","description":"Always-present relevant technologies.","examples":[[{"logo":"https://assets.example/salesforce.svg","name":"Salesforce"}]]},"tech_integration_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tech Integration Title","description":"Technology-integration section title.","examples":["Salesforce integration"]},"tech_integration_examples":{"items":{"type":"string"},"type":"array","title":"Tech Integration Examples","description":"Always-present integration examples.","examples":[["Enrich opportunity review workflows."]]},"tech_integration_questions":{"items":{"type":"string"},"type":"array","title":"Tech Integration Questions","description":"Always-present integration discovery questions.","examples":[["Which Salesforce objects drive forecasting?"]]},"potential_objections":{"items":{"$ref":"#/components/schemas/PublicPlaybookObjection"},"type":"array","title":"Potential Objections","description":"Always-present objections and responses.","examples":[[{"objection":"Implementation will take too long.","response":"Start with the existing Salesforce workflow and a focused pilot."}]]},"meeting_note_example":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Meeting Note Example","description":"Example personalized meeting note.","examples":["Hi Alex, teams like yours use this to remove forecast blind spots."]},"product_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Product Name","description":"Seller product name used in generation.","examples":["Northstar Analytics"]},"product_icon_url":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"uri","title":"Product Icon Url","description":"Optional seller product icon URL.","examples":["https://assets.example/northstar.png"]},"readiness_level":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Readiness Level","description":"Qualitative buying-readiness level.","examples":["active_evaluation"]},"contact_overview":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact Overview","description":"Generated contact summary.","examples":["Alex is the recommended first contact."]},"contact_intelligence":{"items":{"$ref":"#/components/schemas/PublicPlaybookContactIntelligence"},"type":"array","title":"Contact Intelligence","description":"Always-present structured contact intelligence.","examples":[[{"company":"Acme Corporation","linkedin_url":"https://www.linkedin.com/in/alex-morgan","name":"Alex Morgan","role":"Champion","signals":["Hiring for RevOps"],"summary":"Owns the workflow this product improves.","title":"VP Revenue Operations"}]]},"company_context":{"anyOf":[{"$ref":"#/components/schemas/PublicPlaybookCompanyContext"},{"type":"null"}],"description":"Structured company context; null when unavailable.","examples":[{"business_model":"B2B SaaS","competitors":["Contoso"],"employee_count":"501-1000","headquarters":"San Francisco, CA","market_position":"Enterprise revenue-intelligence provider","recent_news":["Expanded enterprise sales team."]}]},"intent_analysis":{"anyOf":[{"$ref":"#/components/schemas/PublicPlaybookIntentAnalysis"},{"type":"null"}],"description":"Structured intent analysis; null when unavailable.","examples":[{"intent_score":"high","signals":["Hiring for RevOps"],"summary":"Signals suggest an active evaluation.","topics":["Revenue operations"]}]},"conversation_strategy":{"anyOf":[{"$ref":"#/components/schemas/PublicPlaybookConversationStrategy"},{"type":"null"}],"description":"Structured conversation strategy; null when unavailable.","examples":[{"approach":"Connect operational pain to the existing planning cycle.","key_questions":["Where do forecast handoffs break down today?"],"opening":"Lead with forecast-quality improvements."}]},"risks_and_challenges":{"anyOf":[{"$ref":"#/components/schemas/PublicPlaybookRisksAndChallenges"},{"type":"null"}],"description":"Structured risks and mitigations; null when unavailable.","examples":[{"mitigations":["Offer a focused pilot with measurable outcomes."],"potential_blockers":["Budget timing"],"risks":["Competing internal initiative"]}]},"highlight_color":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Highlight Color","description":"Optional presentational highlight color supplied by the generator.","examples":["#2563eb"]},"product_text_color":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Product Text Color","description":"Optional presentational product-text color.","examples":["#ffffff"]},"gradient_dark_color":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gradient Dark Color","description":"Optional presentational dark gradient color.","examples":["#0f172a"]},"hero_image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"uri","title":"Hero Image Url","description":"Optional hero-image URL.","examples":["https://assets.example/hero.png"]},"document_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Url","description":"Non-null when the backend produced a fully rendered playbook document; fetch it via `GET /v1/playbooks/{job_id}/document`.","examples":["/pbk_a1b2c3/"]}},"type":"object","title":"PublicPlaybookResult","description":"Typed result of a successful Playbooks job.\n\nScalar fields are always present but nullable when the generator has no\nsupported value. Collection fields are always present and default to an\nempty list. Structured analysis sections are nullable.","examples":[{"business_objective":"Improve enterprise pipeline conversion.","business_summary":"Acme sells revenue-intelligence software to enterprise teams.","company_context":{"business_model":"B2B SaaS","competitors":["Contoso"],"employee_count":"501-1000","headquarters":"San Francisco, CA","market_position":"Enterprise revenue-intelligence provider","recent_news":["Expanded enterprise sales team."]},"company_name":"Acme Corporation","contact_intelligence":[{"company":"Acme Corporation","linkedin_url":"https://www.linkedin.com/in/alex-morgan","name":"Alex Morgan","role":"Champion","signals":["Hiring for RevOps"],"summary":"Owns the workflow this product improves.","title":"VP Revenue Operations"}],"contact_overview":"Alex is the recommended first contact.","conversation_strategy":{"approach":"Connect operational pain to the existing planning cycle.","key_questions":["Where do forecast handoffs break down today?"],"opening":"Lead with forecast-quality improvements."},"domain":"acme.example","industry":"Software","intent_analysis":{"intent_score":"high","signals":["Hiring for RevOps"],"summary":"Signals suggest an active evaluation.","topics":["Revenue operations"]},"key_personas":[{"conversation_starters":["Ask about forecast accuracy."],"description":"Owns revenue-process efficiency and forecasting.","name":"Alex Morgan","tags":["economic_buyer"],"title":"VP Revenue Operations"}],"key_services":["Revenue analytics"],"meeting_note_example":"Hi Alex, teams like yours use this to remove forecast blind spots.","potential_objections":[{"objection":"Implementation will take too long.","response":"Start with the existing Salesforce workflow and a focused pilot."}],"product_name":"Northstar Analytics","readiness_level":"active_evaluation","relevant_tech_stack":[{"logo":"https://assets.example/salesforce.svg","name":"Salesforce"}],"risks_and_challenges":{"mitigations":["Offer a focused pilot with measurable outcomes."],"potential_blockers":["Budget timing"],"risks":["Competing internal initiative"]},"sales_angles":["Connect scattered revenue data."],"tech_integration_examples":["Enrich opportunity review workflows."],"tech_integration_questions":["Which Salesforce objects drive forecasting?"],"tech_integration_title":"Salesforce integration","value_props":["Increase forecast confidence."],"website":"https://acme.example"}]},"PublicPlaybookRisksAndChallenges":{"properties":{"potential_blockers":{"items":{"type":"string"},"type":"array","title":"Potential Blockers","description":"Always-present potential blockers.","examples":[["Budget timing"]]},"risks":{"items":{"type":"string"},"type":"array","title":"Risks","description":"Always-present deal risks.","examples":[["Competing internal initiative"]]},"mitigations":{"items":{"type":"string"},"type":"array","title":"Mitigations","description":"Always-present suggested mitigations.","examples":[["Offer a focused pilot with measurable outcomes."]]}},"type":"object","title":"PublicPlaybookRisksAndChallenges","description":"Risks and mitigations identified for the account strategy.","examples":[{"mitigations":["Offer a focused pilot with measurable outcomes."],"potential_blockers":["Budget timing"],"risks":["Competing internal initiative"]}]},"PublicPlaybookTechnology":{"properties":{"name":{"type":"string","title":"Name","description":"Technology name.","examples":["Salesforce"]},"logo":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"uri","title":"Logo","description":"Optional technology-logo URL.","examples":["https://assets.example/salesforce.svg"]}},"type":"object","required":["name"],"title":"PublicPlaybookTechnology","description":"A technology relevant to the target account's Playbook.","examples":[{"logo":"https://assets.example/salesforce.svg","name":"Salesforce"}]},"PublicPlaybookTemplate":{"properties":{"key":{"type":"string","title":"Key","description":"The key value for this publicplaybooktemplate.","examples":["Example key"]},"name":{"type":"string","title":"Name","description":"The name value for this publicplaybooktemplate.","examples":["Example name"]},"stage":{"type":"string","title":"Stage","description":"The stage value for this publicplaybooktemplate.","examples":["Example stage"]},"focus":{"type":"string","title":"Focus","description":"The focus value for this publicplaybooktemplate.","examples":["Example focus"]},"guidance":{"items":{"type":"string"},"type":"array","title":"Guidance","description":"The guidance value for this publicplaybooktemplate.","examples":[["Example guidance"]]},"recommended_sections":{"items":{"type":"string"},"type":"array","title":"Recommended Sections","default":[],"description":"The recommended sections value for this publicplaybooktemplate."},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"The source value for this publicplaybooktemplate.","examples":["Example source"]},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"The id value for this publicplaybooktemplate.","examples":["Example id"]},"template_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Template State","description":"The template state value for this publicplaybooktemplate.","examples":["Example template state"]},"live_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Live Version","description":"The live version value for this publicplaybooktemplate.","examples":[0]},"has_artifacts":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Artifacts","description":"The has artifacts value for this publicplaybooktemplate.","examples":[true]},"intelligence":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Intelligence","description":"The intelligence value for this publicplaybooktemplate.","examples":["Example intelligence"]},"brief":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brief","description":"The brief value for this publicplaybooktemplate.","examples":["Example brief"]},"prospect_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prospect Type","description":"The prospect type value for this publicplaybooktemplate.","examples":["Example prospect type"]},"offer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Offer Id","description":"The offer id value for this publicplaybooktemplate.","examples":["Example offer id"]},"brand_profile_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand Profile Id","description":"The brand profile id value for this publicplaybooktemplate.","examples":["Example brand profile id"]}},"type":"object","required":["key","name","stage","focus","guidance"],"title":"PublicPlaybookTemplate","description":"One Playbook template: an organization-defined template or a curated\ncatalog entry. Org templates carry lifecycle fields; catalog entries carry\nrecommended sections.","examples":[{"key":"Example key","name":"Example name","stage":"Example stage","focus":"Example focus","guidance":["Example guidance"]}]},"PublicPlaybookTemplateCatalog":{"properties":{"catalog_version":{"type":"string","title":"Catalog Version","description":"The catalog version value for this publicplaybooktemplatecatalog.","examples":["Example catalog version"]},"stages":{"items":{"type":"string"},"type":"array","title":"Stages","description":"The stages value for this publicplaybooktemplatecatalog.","examples":[["Example stages"]]},"templates":{"items":{"$ref":"#/components/schemas/PublicPlaybookTemplate"},"type":"array","title":"Templates","description":"The templates value for this publicplaybooktemplatecatalog.","examples":[[{"key":"Example key","name":"Example name","stage":"Example stage","focus":"Example focus","guidance":["Example guidance"]}]]}},"type":"object","required":["catalog_version","stages","templates"],"title":"PublicPlaybookTemplateCatalog","description":"Versioned Playbook template catalog and shared stage vocabulary.","examples":[{"catalog_version":"Example catalog version","stages":["Example stages"],"templates":[{"key":"Example key","name":"Example name","stage":"Example stage","focus":"Example focus","guidance":["Example guidance"]}]}]},"PublicProspectingEvent":{"properties":{"seq":{"type":"integer","minimum":1.0,"title":"Seq","description":"Monotonic per-run sequence number; pass the response's next_after_seq back as after_seq to page forward.","examples":[7]},"type":{"type":"string","title":"Type","description":"Event kind: agent status line (task_status), streamed assistant message (text), a discovered company (lead), or a lifecycle marker (generation_started, complete, error, stopped).","examples":["text"]},"data":{"additionalProperties":true,"type":"object","title":"Data","description":"Event payload; its shape depends on type — {\"text\": \"...\"} for text, {\"label\": \"...\"} for task_status, a {domain, company_name, contacts[]} object for lead.","examples":[{"text":"Scanning sources for B2B SaaS accounts hiring RevOps leaders..."}]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When the event was recorded; null only for legacy rows.","examples":["2026-07-13T12:00:00Z"]}},"type":"object","required":["seq","type"],"title":"PublicProspectingEvent","description":"One entry in a prospecting run's append-only live thread.\n\nThe agent streams its work as it runs; each frame is persisted so the run's\nprogress and messages can be replayed by sequence.","examples":[{"created_at":"2026-07-13T12:00:00Z","data":{"text":"Scanning sources for B2B SaaS accounts hiring RevOps leaders..."},"seq":7,"type":"text"}]},"PublicProspectingRunEvents":{"properties":{"job":{"$ref":"#/components/schemas/ProspectingJobResponse","description":"Current typed state of the prospecting run.","examples":[{"created_at":"2026-07-13T12:00:00Z","expires_at":"2026-08-12T12:00:00Z","id":"job_prospecting_123","input":{"campaign_name":"North America RevOps leaders","objective":"Find VP Revenue Operations leaders at mid-market B2B SaaS companies.","product_info":"Revenue analytics for B2B SaaS."},"progress":55,"project_id":"proj_123","stages":[{"key":"understand","label":"Understanding the brief","status":"completed"},{"key":"search","label":"Searching the web","status":"running"}],"status":"running","type":"prospecting","usage":{"cost_usd":0.0}}]},"events":{"items":{"$ref":"#/components/schemas/PublicProspectingEvent"},"type":"array","title":"Events","description":"Events with seq greater than the requested after_seq, in ascending order.","examples":[[{"created_at":"2026-07-13T12:00:00Z","data":{"label":"Searching the web"},"seq":6,"type":"task_status"},{"created_at":"2026-07-13T12:00:00Z","data":{"text":"Scanning sources for B2B SaaS accounts hiring RevOps leaders..."},"seq":7,"type":"text"}]]},"next_after_seq":{"type":"integer","minimum":0.0,"title":"Next After Seq","description":"Highest seq returned this page; pass it back as after_seq to fetch only newer events.","examples":[7]}},"type":"object","required":["job","events","next_after_seq"],"title":"PublicProspectingRunEvents","description":"A page of a prospecting run's live thread plus the run's current state.","examples":[{"events":[{"created_at":"2026-07-13T12:00:00Z","data":{"label":"Searching the web"},"seq":6,"type":"task_status"},{"created_at":"2026-07-13T12:00:00Z","data":{"text":"Scanning sources for B2B SaaS accounts hiring RevOps leaders..."},"seq":7,"type":"text"}],"job":{"created_at":"2026-07-13T12:00:00Z","expires_at":"2026-08-12T12:00:00Z","id":"job_prospecting_123","input":{"campaign_name":"North America RevOps leaders","objective":"Find VP Revenue Operations leaders at mid-market B2B SaaS companies.","product_info":"Revenue analytics for B2B SaaS."},"progress":55,"project_id":"proj_123","stages":[{"key":"understand","label":"Understanding the brief","status":"completed"},{"key":"search","label":"Searching the web","status":"running"}],"status":"running","type":"prospecting","usage":{"cost_usd":0.0}},"next_after_seq":7}]},"PublicQuotaStatus":{"properties":{"metric":{"type":"string","enum":["requests","tokens","cost"],"title":"Metric","description":"Usage counter governed by this quota.","examples":["requests"]},"period":{"type":"string","const":"month","title":"Period","description":"UTC calendar period used by this quota.","examples":["month"]},"scope":{"type":"string","enum":["organization","project","api_key"],"title":"Scope","description":"Narrowest tenant scope selected by this quota.","examples":["project"]},"capability_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Capability Key","description":"Capability restriction, or null when all capabilities share the quota.","examples":["playbooks"]},"limit_value":{"type":"number","minimum":0.0,"title":"Limit Value","description":"Configured monthly limit in the metric's units.","examples":[1000]},"used":{"type":"number","minimum":0.0,"title":"Used","description":"Usage recorded in the quota's complete scope this month.","examples":[12]},"remaining":{"type":"number","minimum":0.0,"title":"Remaining","description":"Non-negative limit minus used value.","examples":[988]},"resets_at":{"type":"string","format":"date-time","title":"Resets At","description":"UTC boundary at which the monthly counter resets.","examples":["2026-08-01T00:00:00Z"]}},"type":"object","required":["metric","period","scope","limit_value","used","remaining","resets_at"],"title":"PublicQuotaStatus","description":"One monthly usage quota applicable to the authenticated project key.","examples":[{"capability_key":"playbooks","limit_value":1000,"metric":"requests","period":"month","remaining":988,"resets_at":"2026-08-01T00:00:00Z","scope":"project","used":12}]},"PublicRateLimitPolicy":{"properties":{"limit":{"type":"integer","exclusiveMinimum":0.0,"title":"Limit","description":"Maximum authenticated requests per window.","examples":[120]},"window_seconds":{"type":"integer","exclusiveMinimum":0.0,"title":"Window Seconds","description":"Rate-limit window length in seconds.","examples":[60]}},"type":"object","required":["limit","window_seconds"],"title":"PublicRateLimitPolicy","description":"API-key request-rate policy applied independently of billable usage.","examples":[{"limit":120,"window_seconds":60}]},"PublicUsageByCapability":{"properties":{"requests":{"type":"integer","minimum":0.0,"title":"Requests","description":"New generation jobs accepted in the period. Polls, replays, and rejected requests do not increment this counter.","examples":[12]},"tokens":{"type":"integer","minimum":0.0,"title":"Tokens","description":"Attributed capability tokens in the period.","examples":[45200]},"cost_usd":{"type":"number","minimum":0.0,"title":"Cost Usd","description":"Attributed downstream cost in USD for the period.","examples":[1.243]},"capability_key":{"type":"string","title":"Capability Key","description":"Stable capability key.","examples":["playbooks"]}},"type":"object","required":["requests","tokens","cost_usd","capability_key"],"title":"PublicUsageByCapability","description":"Usage totals for one capability within a project and billing period.","examples":[{"capability_key":"playbooks","cost_usd":1.243,"requests":12,"tokens":45200}]},"PublicUsageResponse":{"properties":{"project_id":{"type":"string","title":"Project Id","description":"Project whose usage is reported.","examples":["proj_123"]},"period":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$","title":"Period","description":"UTC billing period key in `YYYY-MM` form.","examples":["2026-07"]},"period_start":{"type":"string","format":"date-time","title":"Period Start","description":"Inclusive UTC start of the reported monthly period.","examples":["2026-07-01T00:00:00Z"]},"period_end":{"type":"string","format":"date-time","title":"Period End","description":"Exclusive UTC end and reset time of the reported monthly period.","examples":["2026-08-01T00:00:00Z"]},"rollup":{"$ref":"#/components/schemas/PublicUsageRollup","description":"All-capability usage totals for the period.","examples":[{"cost_usd":1.243,"requests":12,"tokens":45200}]},"by_capability":{"items":{"$ref":"#/components/schemas/PublicUsageByCapability"},"type":"array","title":"By Capability","description":"Usage totals for capabilities with recorded usage.","examples":[[{"capability_key":"playbooks","cost_usd":1.243,"requests":12,"tokens":45200}]]},"rate_limit":{"$ref":"#/components/schemas/PublicRateLimitPolicy","description":"Per-API-key request rate policy. Current-window counters are returned in response headers.","examples":[{"limit":120,"window_seconds":60}]},"usage_tier":{"anyOf":[{"$ref":"#/components/schemas/PublicUsageTier"},{"type":"null"}],"description":"The organization's current usage tier, or null when tiers are not configured. The rate limit and a monthly spend cap derive from it.","examples":[{"key":"tier_1","monthly_cost_cap_usd":500.0,"name":"Tier 1","rank":1,"rate_limit_per_minute":120}]},"quotas":{"items":{"$ref":"#/components/schemas/PublicQuotaStatus"},"type":"array","title":"Quotas","description":"Monthly quotas that can block this project key; empty when none apply.","examples":[[{"capability_key":"playbooks","limit_value":1000,"metric":"requests","period":"month","remaining":988,"resets_at":"2026-08-01T00:00:00Z","scope":"project","used":12}]]},"budgets":{"items":{"$ref":"#/components/schemas/PublicBudgetStatus"},"type":"array","title":"Budgets","description":"Monthly budgets that can affect this project; empty when none apply.","examples":[[{"hard_limit":true,"limit_usd":50,"period":"month","remaining_usd":48.757,"resets_at":"2026-08-01T00:00:00Z","scope":"project","spend_usd":1.243}]]},"credits":{"$ref":"#/components/schemas/PublicCredits","description":"Organization prepaid-credit context.","examples":[{"balance_usd":98.757,"billing_enabled":true,"topup_increment_usd":25.0}]}},"type":"object","required":["project_id","period","period_start","period_end","rollup","by_capability","rate_limit","quotas","budgets","credits"],"title":"PublicUsageResponse","description":"Month-to-date project usage and prepaid-credit information.","examples":[{"budgets":[{"hard_limit":true,"limit_usd":50,"period":"month","remaining_usd":48.757,"resets_at":"2026-08-01T00:00:00Z","scope":"project","spend_usd":1.243}],"by_capability":[{"capability_key":"playbooks","cost_usd":1.243,"requests":12,"tokens":45200}],"credits":{"balance_usd":98.757,"billing_enabled":true,"topup_increment_usd":25.0},"period":"2026-07","period_end":"2026-08-01T00:00:00Z","period_start":"2026-07-01T00:00:00Z","project_id":"proj_123","quotas":[{"capability_key":"playbooks","limit_value":1000,"metric":"requests","period":"month","remaining":988,"resets_at":"2026-08-01T00:00:00Z","scope":"project","used":12}],"rate_limit":{"limit":120,"window_seconds":60},"rollup":{"cost_usd":1.243,"requests":12,"tokens":45200},"usage_tier":{"key":"tier_1","monthly_cost_cap_usd":500.0,"name":"Tier 1","rank":1,"rate_limit_per_minute":120}}]},"PublicUsageRollup":{"properties":{"requests":{"type":"integer","minimum":0.0,"title":"Requests","description":"New generation jobs accepted in the period. Polls, replays, and rejected requests do not increment this counter.","examples":[12]},"tokens":{"type":"integer","minimum":0.0,"title":"Tokens","description":"Attributed capability tokens in the period.","examples":[45200]},"cost_usd":{"type":"number","minimum":0.0,"title":"Cost Usd","description":"Attributed downstream cost in USD for the period.","examples":[1.243]}},"type":"object","required":["requests","tokens","cost_usd"],"title":"PublicUsageRollup","description":"Usage totals for a project and billing period.","examples":[{"cost_usd":1.243,"requests":12,"tokens":45200}]},"PublicUsageTier":{"properties":{"key":{"type":"string","title":"Key","description":"Stable tier key.","examples":["tier_1"]},"name":{"type":"string","title":"Name","description":"Human-readable tier name.","examples":["Tier 1"]},"rank":{"type":"integer","minimum":0.0,"title":"Rank","description":"Tier position; higher ranks have higher limits.","examples":[1]},"rate_limit_per_minute":{"type":"integer","exclusiveMinimum":0.0,"title":"Rate Limit Per Minute","description":"Authenticated requests per minute allowed at this tier.","examples":[120]},"monthly_cost_cap_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Monthly Cost Cap Usd","description":"Monthly attributed-cost ceiling in USD at this tier, or null when uncapped.","examples":[500.0]}},"type":"object","required":["key","name","rank","rate_limit_per_minute"],"title":"PublicUsageTier","description":"The organization's current usage tier. Tiers grow with cumulative paid\nusage and account age; each tier sets the request rate limit and the\nmonthly spend cap.","examples":[{"key":"tier_1","monthly_cost_cap_usd":500.0,"name":"Tier 1","rank":1,"rate_limit_per_minute":120}]},"PublicValidationIssue":{"properties":{"type":{"type":"string","title":"Type","description":"Pydantic validation error category.","examples":["missing"]},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Loc","description":"Location of the invalid value, beginning with `body`, `query`, or `path`.","examples":[["body","target_company"]]},"msg":{"type":"string","title":"Msg","description":"Human-readable validation explanation.","examples":["Field required"]}},"type":"object","required":["type","loc","msg"],"title":"PublicValidationIssue","description":"One supplemental input-validation issue returned with `invalid_request`.","examples":[{"loc":["body","target_company"],"msg":"Field required","type":"missing"}]},"Qualification":{"properties":{"status":{"type":"string","enum":["qualified","rejected","unknown"],"title":"Status","description":"The status value for this qualification.","examples":["qualified"]},"score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Score","description":"The score value for this qualification.","examples":[0.0]},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence","description":"The confidence value for this qualification.","examples":[0.0]},"reason":{"type":"string","maxLength":2000,"title":"Reason","description":"The reason value for this qualification.","examples":["Example reason"]},"selection_strategy":{"type":"string","enum":["cold_start","explore","exploit"],"title":"Selection Strategy","description":"The selection strategy value for this qualification.","examples":["cold_start"]},"evidence_ids":{"items":{"type":"string"},"type":"array","maxItems":100,"title":"Evidence Ids","description":"The evidence ids value for this qualification.","examples":[["Example evidence ids"]]}},"type":"object","required":["status","score","confidence","reason","selection_strategy"],"title":"Qualification","description":"Structured qualification data exposed by the public API.","examples":[{"status":"qualified","score":0.0,"confidence":0.0,"reason":"Example reason","selection_strategy":"cold_start"}]},"QualificationContextPolicy":{"properties":{"seller_context_source":{"type":"string","const":"prospecting_job_input","title":"Seller Context Source","description":"The seller context source value for this qualificationcontextpolicy."},"product_info_required_at_execution":{"type":"boolean","const":true,"title":"Product Info Required At Execution","description":"The product info required at execution value for this qualificationcontextpolicy."},"objective_required_at_execution":{"type":"boolean","const":true,"title":"Objective Required At Execution","description":"The objective required at execution value for this qualificationcontextpolicy."},"real_prospecting_evidence_required":{"type":"boolean","const":true,"title":"Real Prospecting Evidence Required","description":"The real prospecting evidence required value for this qualificationcontextpolicy."}},"additionalProperties":false,"type":"object","required":["seller_context_source","product_info_required_at_execution","objective_required_at_execution","real_prospecting_evidence_required"],"title":"QualificationContextPolicy","description":"Structured qualificationcontextpolicy data exposed by the public API.","examples":[{"seller_context_source":"prospecting_job_input","product_info_required_at_execution":true,"objective_required_at_execution":true,"real_prospecting_evidence_required":true}]},"QualificationDimension":{"type":"string","enum":["industry_match","company_need","position_relevance","seniority_match","deal_size_potential"],"title":"QualificationDimension","description":"Structured qualificationdimension data exposed by the public API.","examples":["industry_match"]},"QualificationDimensionSpecification":{"properties":{"dimension":{"$ref":"#/components/schemas/QualificationDimension","description":"The dimension value for this qualificationdimensionspecification.","examples":["industry_match"]},"weight_percent":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Weight Percent","description":"The weight percent value for this qualificationdimensionspecification.","examples":[0]},"subject":{"$ref":"#/components/schemas/QualificationSubject","description":"The subject value for this qualificationdimensionspecification.","examples":["company"]},"evidence_fields":{"items":{"$ref":"#/components/schemas/QualificationEvidenceField"},"type":"array","maxItems":3,"minItems":1,"title":"Evidence Fields","description":"The evidence fields value for this qualificationdimensionspecification.","examples":[["company_description"]]},"max_freshness_days":{"type":"integer","maximum":365.0,"minimum":1.0,"title":"Max Freshness Days","description":"The max freshness days value for this qualificationdimensionspecification.","examples":[1]},"evidence_required":{"type":"boolean","const":true,"title":"Evidence Required","description":"The evidence required value for this qualificationdimensionspecification."},"insufficient_evidence_behavior":{"type":"string","const":"unscored","title":"Insufficient Evidence Behavior","description":"The insufficient evidence behavior value for this qualificationdimensionspecification."}},"additionalProperties":false,"type":"object","required":["dimension","weight_percent","subject","evidence_fields","max_freshness_days","evidence_required","insufficient_evidence_behavior"],"title":"QualificationDimensionSpecification","description":"Structured qualificationdimensionspecification data exposed by the public API.","examples":[{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"}]},"QualificationDimensionWeightIn":{"properties":{"dimension":{"$ref":"#/components/schemas/QualificationDimension","description":"The dimension value for this qualificationdimensionweightin.","examples":["industry_match"]},"weight_percent":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Weight Percent","description":"The weight percent value for this qualificationdimensionweightin.","examples":[0]}},"additionalProperties":false,"type":"object","required":["dimension","weight_percent"],"title":"QualificationDimensionWeightIn","description":"Structured qualificationdimensionweightin data exposed by the public API.","examples":[{"dimension":"industry_match","weight_percent":0}]},"QualificationEvidenceField":{"type":"string","enum":["company_description","company_headcount","company_industry","person_job_title","person_seniority","research_evidence"],"title":"QualificationEvidenceField","description":"Structured qualificationevidencefield data exposed by the public API.","examples":["company_description"]},"QualificationGradeBand":{"properties":{"grade":{"type":"string","enum":["A","B","C"],"title":"Grade","description":"The grade value for this qualificationgradeband.","examples":["A"]},"min_score":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Min Score","description":"The min score value for this qualificationgradeband.","examples":[0]},"max_score":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Max Score","description":"The max score value for this qualificationgradeband.","examples":[0]}},"additionalProperties":false,"type":"object","required":["grade","min_score","max_score"],"title":"QualificationGradeBand","description":"Structured qualificationgradeband data exposed by the public API.","examples":[{"grade":"A","min_score":0,"max_score":0}]},"QualificationPolicyCreateIn":{"properties":{"key":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","title":"Key","description":"The key value for this qualificationpolicycreatein.","examples":["example-key"]},"target":{"$ref":"#/components/schemas/QualificationTargetIn","description":"The target value for this qualificationpolicycreatein.","examples":[{"industries":["ai_ml"],"seniorities":["c_suite"]}]},"dimensions":{"items":{"$ref":"#/components/schemas/QualificationDimensionWeightIn"},"type":"array","maxItems":5,"minItems":5,"title":"Dimensions","description":"The dimensions value for this qualificationpolicycreatein.","examples":[[{"dimension":"industry_match","weight_percent":0},{"dimension":"industry_match","weight_percent":0},{"dimension":"industry_match","weight_percent":0},{"dimension":"industry_match","weight_percent":0},{"dimension":"industry_match","weight_percent":0}]]},"expected_policy_version":{"$ref":"#/components/schemas/QualificationPolicyVersion","description":"The expected policy version value for this qualificationpolicycreatein.","examples":["2026-07-13"]},"reason":{"type":"string","maxLength":500,"minLength":3,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"Reason","description":"The reason value for this qualificationpolicycreatein.","examples":["Example value"]}},"additionalProperties":false,"type":"object","required":["key","target","dimensions","expected_policy_version","reason"],"title":"QualificationPolicyCreateIn","description":"Freeze a scoring rubric; this input cannot carry prompts, URLs, secrets, or records.","examples":[{"key":"example-key","target":{"industries":["ai_ml"],"seniorities":["c_suite"]},"dimensions":[{"dimension":"industry_match","weight_percent":0},{"dimension":"industry_match","weight_percent":0},{"dimension":"industry_match","weight_percent":0},{"dimension":"industry_match","weight_percent":0},{"dimension":"industry_match","weight_percent":0}],"expected_policy_version":"2026-07-13","reason":"Example value"}]},"QualificationPolicyListOut":{"properties":{"policies":{"items":{"$ref":"#/components/schemas/QualificationPolicyOut"},"type":"array","title":"Policies","description":"The policies value for this qualificationpolicylistout.","examples":[[{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"qualpolicy_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","policy_version":"2026-07-13","target":{"industries":["ai_ml"],"seniorities":["c_suite"]},"dimension_specs":[{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"}],"score_policy":{"minimum_score":0,"maximum_score":100,"weighted_rounding":"nearest_integer","missing_evidence_behavior":"unscored","grade_bands":[{"grade":"A","min_score":0,"max_score":0},{"grade":"A","min_score":0,"max_score":0},{"grade":"A","min_score":0,"max_score":0}]},"context_policy":{"seller_context_source":"prospecting_job_input","product_info_required_at_execution":true,"objective_required_at_execution":true,"real_prospecting_evidence_required":true},"policy_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","scoring_available":false,"scoring_authorized":false,"model_requests_made":0,"search_requests_made":0,"prospects_scored":0,"prospecting_jobs_modified":0,"audience_members_modified":0,"outreach_drafts_generated":0,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}]]},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"The total value for this qualificationpolicylistout.","examples":[0]},"limit":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Limit","description":"The limit value for this qualificationpolicylistout.","examples":[1]},"offset":{"type":"integer","maximum":10000.0,"minimum":0.0,"title":"Offset","description":"The offset value for this qualificationpolicylistout.","examples":[0]},"availability":{"type":"string","const":"contract_only","title":"Availability","description":"The availability value for this qualificationpolicylistout."},"scoring_available":{"type":"boolean","const":false,"title":"Scoring Available","description":"The scoring available value for this qualificationpolicylistout."},"model_requests_made":{"type":"integer","const":0,"title":"Model Requests Made","description":"The model requests made value for this qualificationpolicylistout."},"search_requests_made":{"type":"integer","const":0,"title":"Search Requests Made","description":"The search requests made value for this qualificationpolicylistout."}},"additionalProperties":false,"type":"object","required":["policies","total","limit","offset","availability","scoring_available","model_requests_made","search_requests_made"],"title":"QualificationPolicyListOut","description":"Structured qualificationpolicylistout data exposed by the public API.","examples":[{"policies":[{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"qualpolicy_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","policy_version":"2026-07-13","target":{"industries":["ai_ml"],"seniorities":["c_suite"]},"dimension_specs":[{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"}],"score_policy":{"minimum_score":0,"maximum_score":100,"weighted_rounding":"nearest_integer","missing_evidence_behavior":"unscored","grade_bands":[{"grade":"A","min_score":0,"max_score":0},{"grade":"A","min_score":0,"max_score":0},{"grade":"A","min_score":0,"max_score":0}]},"context_policy":{"seller_context_source":"prospecting_job_input","product_info_required_at_execution":true,"objective_required_at_execution":true,"real_prospecting_evidence_required":true},"policy_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","scoring_available":false,"scoring_authorized":false,"model_requests_made":0,"search_requests_made":0,"prospects_scored":0,"prospecting_jobs_modified":0,"audience_members_modified":0,"outreach_drafts_generated":0,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}],"total":0,"limit":1,"offset":0,"availability":"contract_only","scoring_available":false,"model_requests_made":0,"search_requests_made":0}]},"QualificationPolicyOut":{"properties":{"schema_version":{"$ref":"#/components/schemas/QualificationPolicySchemaVersion","description":"The schema version value for this qualificationpolicyout.","examples":["2026-07-13"]},"status":{"type":"string","const":"specified","title":"Status","description":"The status value for this qualificationpolicyout."},"availability":{"type":"string","const":"contract_only","title":"Availability","description":"The availability value for this qualificationpolicyout."},"id":{"type":"string","pattern":"^qualpolicy_[a-f0-9]{24}$","title":"Id","description":"The id value for this qualificationpolicyout.","examples":["qualpolicy_aaaaaaaaaaaaaaaaaaaaaaaa"]},"idempotent_replay":{"type":"boolean","title":"Idempotent Replay","description":"The idempotent replay value for this qualificationpolicyout.","examples":[true]},"key":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","title":"Key","description":"The key value for this qualificationpolicyout.","examples":["example-key"]},"project_id":{"type":"string","pattern":"^proj_[a-f0-9]{24}$","title":"Project Id","description":"The project id value for this qualificationpolicyout.","examples":["proj_aaaaaaaaaaaaaaaaaaaaaaaa"]},"environment":{"type":"string","enum":["live","test"],"title":"Environment","description":"The environment value for this qualificationpolicyout.","examples":["live"]},"policy_version":{"$ref":"#/components/schemas/QualificationPolicyVersion","description":"The policy version value for this qualificationpolicyout.","examples":["2026-07-13"]},"target":{"$ref":"#/components/schemas/QualificationTargetOut","description":"The target value for this qualificationpolicyout.","examples":[{"industries":["ai_ml"],"seniorities":["c_suite"]}]},"dimension_specs":{"items":{"$ref":"#/components/schemas/QualificationDimensionSpecification"},"type":"array","maxItems":5,"minItems":5,"title":"Dimension Specs","description":"The dimension specs value for this qualificationpolicyout.","examples":[[{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"}]]},"score_policy":{"$ref":"#/components/schemas/QualificationScorePolicy","description":"The score policy value for this qualificationpolicyout.","examples":[{"minimum_score":0,"maximum_score":100,"weighted_rounding":"nearest_integer","missing_evidence_behavior":"unscored","grade_bands":[{"grade":"A","min_score":0,"max_score":0},{"grade":"A","min_score":0,"max_score":0},{"grade":"A","min_score":0,"max_score":0}]}]},"context_policy":{"$ref":"#/components/schemas/QualificationContextPolicy","description":"The context policy value for this qualificationpolicyout.","examples":[{"seller_context_source":"prospecting_job_input","product_info_required_at_execution":true,"objective_required_at_execution":true,"real_prospecting_evidence_required":true}]},"policy_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Policy Hash","description":"The policy hash value for this qualificationpolicyout.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"reason":{"type":"string","maxLength":500,"minLength":3,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"Reason","description":"The reason value for this qualificationpolicyout.","examples":["Example value"]},"scoring_available":{"type":"boolean","const":false,"title":"Scoring Available","description":"The scoring available value for this qualificationpolicyout."},"scoring_authorized":{"type":"boolean","const":false,"title":"Scoring Authorized","description":"The scoring authorized value for this qualificationpolicyout."},"model_requests_made":{"type":"integer","const":0,"title":"Model Requests Made","description":"The model requests made value for this qualificationpolicyout."},"search_requests_made":{"type":"integer","const":0,"title":"Search Requests Made","description":"The search requests made value for this qualificationpolicyout."},"prospects_scored":{"type":"integer","const":0,"title":"Prospects Scored","description":"The prospects scored value for this qualificationpolicyout."},"prospecting_jobs_modified":{"type":"integer","const":0,"title":"Prospecting Jobs Modified","description":"The prospecting jobs modified value for this qualificationpolicyout."},"audience_members_modified":{"type":"integer","const":0,"title":"Audience Members Modified","description":"The audience members modified value for this qualificationpolicyout."},"outreach_drafts_generated":{"type":"integer","const":0,"title":"Outreach Drafts Generated","description":"The outreach drafts generated value for this qualificationpolicyout."},"outbound_authorized":{"type":"boolean","const":false,"title":"Outbound Authorized","description":"The outbound authorized value for this qualificationpolicyout."},"crm_mutation_authorized":{"type":"boolean","const":false,"title":"Crm Mutation Authorized","description":"The crm mutation authorized value for this qualificationpolicyout."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"The created at value for this qualificationpolicyout.","examples":["2026-07-16T00:00:00Z"]}},"additionalProperties":false,"type":"object","required":["schema_version","status","availability","id","idempotent_replay","key","project_id","environment","policy_version","target","dimension_specs","score_policy","context_policy","policy_hash","reason","scoring_available","scoring_authorized","model_requests_made","search_requests_made","prospects_scored","prospecting_jobs_modified","audience_members_modified","outreach_drafts_generated","outbound_authorized","crm_mutation_authorized","created_at"],"title":"QualificationPolicyOut","description":"Persisted contract-only rubric. Every execution/effect field remains false or zero.","examples":[{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"qualpolicy_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","policy_version":"2026-07-13","target":{"industries":["ai_ml"],"seniorities":["c_suite"]},"dimension_specs":[{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"},{"dimension":"industry_match","weight_percent":0,"subject":"company","evidence_fields":["company_description"],"max_freshness_days":1,"evidence_required":true,"insufficient_evidence_behavior":"unscored"}],"score_policy":{"minimum_score":0,"maximum_score":100,"weighted_rounding":"nearest_integer","missing_evidence_behavior":"unscored","grade_bands":[{"grade":"A","min_score":0,"max_score":0},{"grade":"A","min_score":0,"max_score":0},{"grade":"A","min_score":0,"max_score":0}]},"context_policy":{"seller_context_source":"prospecting_job_input","product_info_required_at_execution":true,"objective_required_at_execution":true,"real_prospecting_evidence_required":true},"policy_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","scoring_available":false,"scoring_authorized":false,"model_requests_made":0,"search_requests_made":0,"prospects_scored":0,"prospecting_jobs_modified":0,"audience_members_modified":0,"outreach_drafts_generated":0,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}]},"QualificationPolicySchemaVersion":{"type":"string","enum":["2026-07-13"],"title":"QualificationPolicySchemaVersion","description":"Readable historical response schemas; append versions, never replace them.","examples":["2026-07-13"]},"QualificationPolicyVersion":{"type":"string","enum":["2026-07-13"],"title":"QualificationPolicyVersion","description":"Readable/replayable scoring policies; append versions, never replace them.","examples":["2026-07-13"]},"QualificationScorePolicy":{"properties":{"minimum_score":{"type":"integer","const":0,"title":"Minimum Score","description":"The minimum score value for this qualificationscorepolicy."},"maximum_score":{"type":"integer","const":100,"title":"Maximum Score","description":"The maximum score value for this qualificationscorepolicy."},"weighted_rounding":{"type":"string","const":"nearest_integer","title":"Weighted Rounding","description":"The weighted rounding value for this qualificationscorepolicy."},"missing_evidence_behavior":{"type":"string","const":"unscored","title":"Missing Evidence Behavior","description":"The missing evidence behavior value for this qualificationscorepolicy."},"grade_bands":{"items":{"$ref":"#/components/schemas/QualificationGradeBand"},"type":"array","maxItems":3,"minItems":3,"title":"Grade Bands","description":"The grade bands value for this qualificationscorepolicy.","examples":[[{"grade":"A","min_score":0,"max_score":0},{"grade":"A","min_score":0,"max_score":0},{"grade":"A","min_score":0,"max_score":0}]]}},"additionalProperties":false,"type":"object","required":["minimum_score","maximum_score","weighted_rounding","missing_evidence_behavior","grade_bands"],"title":"QualificationScorePolicy","description":"Structured qualificationscorepolicy data exposed by the public API.","examples":[{"minimum_score":0,"maximum_score":100,"weighted_rounding":"nearest_integer","missing_evidence_behavior":"unscored","grade_bands":[{"grade":"A","min_score":0,"max_score":0},{"grade":"A","min_score":0,"max_score":0},{"grade":"A","min_score":0,"max_score":0}]}]},"QualificationSubject":{"type":"string","enum":["company","person"],"title":"QualificationSubject","description":"Structured qualificationsubject data exposed by the public API.","examples":["company"]},"QualificationTargetIn":{"properties":{"industries":{"items":{"$ref":"#/components/schemas/TargetIndustry"},"type":"array","maxItems":8,"minItems":1,"title":"Industries","description":"The industries value for this qualificationtargetin.","examples":[["ai_ml"]]},"seniorities":{"items":{"$ref":"#/components/schemas/TargetSeniority"},"type":"array","maxItems":5,"minItems":1,"title":"Seniorities","description":"The seniorities value for this qualificationtargetin.","examples":[["c_suite"]]}},"additionalProperties":false,"type":"object","required":["industries","seniorities"],"title":"QualificationTargetIn","description":"Structured qualificationtargetin data exposed by the public API.","examples":[{"industries":["ai_ml"],"seniorities":["c_suite"]}]},"QualificationTargetOut":{"properties":{"industries":{"items":{"$ref":"#/components/schemas/TargetIndustry"},"type":"array","title":"Industries","description":"The industries value for this qualificationtargetout.","examples":[["ai_ml"]]},"seniorities":{"items":{"$ref":"#/components/schemas/TargetSeniority"},"type":"array","title":"Seniorities","description":"The seniorities value for this qualificationtargetout.","examples":[["c_suite"]]}},"additionalProperties":false,"type":"object","required":["industries","seniorities"],"title":"QualificationTargetOut","description":"Structured qualificationtargetout data exposed by the public API.","examples":[{"industries":["ai_ml"],"seniorities":["c_suite"]}]},"QualityScore":{"properties":{"relevance":{"type":"integer","maximum":25.0,"minimum":0.0,"title":"Relevance","description":"The relevance value for this qualityscore.","examples":[0]},"evidence":{"type":"integer","maximum":20.0,"minimum":0.0,"title":"Evidence","description":"The evidence value for this qualityscore.","examples":[0]},"clarity":{"type":"integer","maximum":15.0,"minimum":0.0,"title":"Clarity","description":"The clarity value for this qualityscore.","examples":[0]},"recipient_value":{"type":"integer","maximum":15.0,"minimum":0.0,"title":"Recipient Value","description":"The recipient value value for this qualityscore.","examples":[0]},"cta":{"type":"integer","maximum":10.0,"minimum":0.0,"title":"Cta","description":"The cta value for this qualityscore.","examples":[0]},"trust":{"type":"integer","maximum":10.0,"minimum":0.0,"title":"Trust","description":"The trust value for this qualityscore.","examples":[0]},"mobile_readability":{"type":"integer","maximum":5.0,"minimum":0.0,"title":"Mobile Readability","description":"The mobile readability value for this qualityscore.","examples":[0]},"total":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Total","description":"The total value for this qualityscore.","examples":[0]},"passed":{"type":"boolean","title":"Passed","description":"The passed value for this qualityscore.","examples":[true]},"issues":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Issues","description":"The issues value for this qualityscore.","examples":[["Example issues"]]}},"additionalProperties":false,"type":"object","required":["relevance","evidence","clarity","recipient_value","cta","trust","mobile_readability","total","passed"],"title":"QualityScore","description":"Structured qualityscore data exposed by the public API.","examples":[{"relevance":0,"evidence":0,"clarity":0,"recipient_value":0,"cta":0,"trust":0,"mobile_readability":0,"total":0,"passed":true}]},"ResearchSource":{"properties":{"id":{"type":"string","maxLength":80,"title":"Id","description":"The id value for this researchsource.","examples":["Example id"]},"url":{"type":"string","maxLength":2000,"title":"Url","description":"The url value for this researchsource.","examples":["https://example.com"]},"title":{"type":"string","maxLength":500,"title":"Title","description":"The title value for this researchsource.","examples":["Example title"]},"publisher":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Publisher","description":"The publisher value for this researchsource.","examples":["Example publisher"]},"source_type":{"type":"string","enum":["official","social","press","third_party","asset","other"],"title":"Source Type","description":"The source type value for this researchsource.","examples":["official"]},"notes":{"anyOf":[{"type":"string","maxLength":800},{"type":"null"}],"title":"Notes","description":"The notes value for this researchsource.","examples":["Example notes"]}},"additionalProperties":false,"type":"object","required":["id","url","title","source_type"],"title":"ResearchSource","description":"Structured researchsource data exposed by the public API.","examples":[{"id":"Example id","url":"https://example.com","title":"Example title","source_type":"official"}]},"ScoreCapRule":{"properties":{"tier":{"type":"string","enum":["tier0","tier1","tier2"],"title":"Tier","description":"The tier value for this scorecaprule.","examples":["tier0"]},"condition":{"type":"string","maxLength":300,"minLength":3,"title":"Condition","description":"The condition value for this scorecaprule.","examples":["Example condition"]},"maximum_score":{"type":"integer","maximum":100.0,"minimum":5.0,"title":"Maximum Score","description":"The maximum score value for this scorecaprule.","examples":[5]}},"additionalProperties":false,"type":"object","required":["tier","condition","maximum_score"],"title":"ScoreCapRule","description":"Structured scorecaprule data exposed by the public API.","examples":[{"tier":"tier0","condition":"Example condition","maximum_score":5}]},"ScoreGradeBand":{"properties":{"grade":{"type":"string","enum":["A+","A","B","C","D","F"],"title":"Grade","description":"The grade value for this scoregradeband.","examples":["A+"]},"minimum_score":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Minimum Score","description":"The minimum score value for this scoregradeband.","examples":[0]},"maximum_score":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Maximum Score","description":"The maximum score value for this scoregradeband.","examples":[0]}},"additionalProperties":false,"type":"object","required":["grade","minimum_score","maximum_score"],"title":"ScoreGradeBand","description":"Structured scoregradeband data exposed by the public API.","examples":[{"grade":"A+","minimum_score":0,"maximum_score":0}]},"ScoreVisibilityBand":{"properties":{"band":{"type":"string","enum":["Excellent","Strong","Moderate","Weak","Critical"],"title":"Band","description":"The band value for this scorevisibilityband.","examples":["Excellent"]},"minimum_score":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Minimum Score","description":"The minimum score value for this scorevisibilityband.","examples":[0]},"maximum_score":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Maximum Score","description":"The maximum score value for this scorevisibilityband.","examples":[0]}},"additionalProperties":false,"type":"object","required":["band","minimum_score","maximum_score"],"title":"ScoreVisibilityBand","description":"Structured scorevisibilityband data exposed by the public API.","examples":[{"band":"Excellent","minimum_score":0,"maximum_score":0}]},"SectionConfidence":{"properties":{"section":{"type":"string","maxLength":120,"title":"Section","description":"The section value for this sectionconfidence.","examples":["Example section"]},"confidence":{"type":"string","enum":["high","medium","low"],"title":"Confidence","description":"The confidence value for this sectionconfidence.","examples":["high"]},"rationale":{"type":"string","maxLength":800,"title":"Rationale","description":"The rationale value for this sectionconfidence.","examples":["Example rationale"]},"source_ids":{"items":{"type":"string"},"type":"array","maxItems":30,"title":"Source Ids","description":"The source ids value for this sectionconfidence.","examples":[["Example source ids"]]}},"additionalProperties":false,"type":"object","required":["section","confidence","rationale"],"title":"SectionConfidence","description":"Structured sectionconfidence data exposed by the public API.","examples":[{"section":"Example section","confidence":"high","rationale":"Example rationale"}]},"SectionEvidence":{"properties":{"source_ids":{"items":{"type":"string"},"type":"array","maxItems":30,"title":"Source Ids","description":"The source ids value for this sectionevidence.","examples":[["Example source ids"]]},"confidence":{"type":"string","enum":["high","medium","low"],"title":"Confidence","default":"low","description":"The confidence value for this sectionevidence."},"notes":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Notes","description":"The notes value for this sectionevidence.","examples":["Example notes"]}},"additionalProperties":false,"type":"object","title":"SectionEvidence","description":"Structured sectionevidence data exposed by the public API.","examples":[{}]},"SenderIdentity":{"properties":{"name":{"type":"string","maxLength":120,"minLength":1,"title":"Name","description":"The name value for this senderidentity.","examples":["Example name"]},"role":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"title":"Role","description":"The role value for this senderidentity.","examples":["Example role"]},"company":{"type":"string","maxLength":160,"minLength":1,"title":"Company","description":"The company value for this senderidentity.","examples":["Example company"]},"reply_email":{"type":"string","maxLength":320,"minLength":3,"pattern":"^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$","title":"Reply Email","description":"The reply email value for this senderidentity.","examples":["Example reply email"]},"postal_address":{"anyOf":[{"type":"string","maxLength":500,"minLength":5},{"type":"null"}],"title":"Postal Address","description":"The postal address value for this senderidentity.","examples":["Example postal address"]}},"additionalProperties":false,"type":"object","required":["name","company","reply_email"],"title":"SenderIdentity","description":"Structured senderidentity data exposed by the public API.","examples":[{"name":"Example name","company":"Example company","reply_email":"Example reply email"}]},"SeverityCreditPolicy":{"properties":{"passed":{"type":"number","const":1.0,"title":"Passed","description":"The passed value for this severitycreditpolicy."},"notice":{"type":"number","const":0.7,"title":"Notice","description":"The notice value for this severitycreditpolicy."},"warning":{"type":"number","const":0.3,"title":"Warning","description":"The warning value for this severitycreditpolicy."},"error":{"type":"number","const":0.0,"title":"Error","description":"The error value for this severitycreditpolicy."}},"additionalProperties":false,"type":"object","required":["passed","notice","warning","error"],"title":"SeverityCreditPolicy","description":"Structured severitycreditpolicy data exposed by the public API.","examples":[{"passed":1.0,"notice":0.7,"warning":0.3,"error":0.0}]},"SimilarCompany":{"properties":{"domain":{"type":"string","title":"Domain","description":"The similar company's bare domain.","examples":["salesloft.com"]},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Company display name.","examples":["Salesloft"]},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary","description":"Short business summary.","examples":["Sales engagement platform for revenue teams."]},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry","description":"Primary industry label.","examples":["Software"]},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"Primary country code.","examples":["US"]},"score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Score","description":"Similarity score (0–1, higher is more similar).","examples":[0.49]}},"type":"object","required":["domain"],"title":"SimilarCompany","description":"A lookalike company from the research backend's similarity index.","examples":[{"domain":"salesloft.com"}]},"SiteAuditCategoryCounts":{"properties":{"technical":{"type":"integer","const":16,"title":"Technical","description":"The technical value for this siteauditcategorycounts."},"structured_data":{"type":"integer","const":6,"title":"Structured Data","description":"The structured data value for this siteauditcategorycounts."},"ai_crawler":{"type":"integer","const":4,"title":"Ai Crawler","description":"The ai crawler value for this siteauditcategorycounts."},"authority":{"type":"integer","const":3,"title":"Authority","description":"The authority value for this siteauditcategorycounts."}},"additionalProperties":false,"type":"object","required":["technical","structured_data","ai_crawler","authority"],"title":"SiteAuditCategoryCounts","description":"Structured siteauditcategorycounts data exposed by the public API.","examples":[{"technical":16,"structured_data":6,"ai_crawler":4,"authority":3}]},"SiteAuditCheckCategory":{"type":"string","enum":["technical","structured_data","ai_crawler","authority"],"title":"SiteAuditCheckCategory","description":"Structured siteauditcheckcategory data exposed by the public API.","examples":["technical"]},"SiteAuditCheckId":{"type":"string","enum":["title_tag","meta_description","h1_tag","heading_structure","image_alt_text","mobile_viewport","structured_data_presence","https","canonical_tag","robots_meta","content_word_count","internal_linking","language_tag","sitemap_xml","response_time","hreflang_tags","org_schema_completeness","faq_schema","content_schema","sameas_links","content_freshness","jsonld_validation","oai_searchbot_access","claude_searchbot_access","claude_user_access","perplexitybot_access","about_page","contact_info","social_proof_links"],"title":"SiteAuditCheckId","description":"Structured siteauditcheckid data exposed by the public API.","examples":["title_tag"]},"SiteAuditCheckProfile":{"type":"string","enum":["aeo_site_readiness_29"],"title":"SiteAuditCheckProfile","description":"Structured siteauditcheckprofile data exposed by the public API.","examples":["aeo_site_readiness_29"]},"SiteAuditCheckSpecification":{"properties":{"check":{"$ref":"#/components/schemas/SiteAuditCheckId","description":"The check value for this siteauditcheckspecification.","examples":["title_tag"]},"source_check":{"type":"string","maxLength":80,"minLength":1,"title":"Source Check","description":"The source check value for this siteauditcheckspecification.","examples":["Example source check"]},"category":{"$ref":"#/components/schemas/SiteAuditCheckCategory","description":"The category value for this siteauditcheckspecification.","examples":["technical"]},"score_impact":{"type":"integer","maximum":15.0,"minimum":1.0,"title":"Score Impact","description":"The score impact value for this siteauditcheckspecification.","examples":[1]},"evaluation_rule":{"type":"string","maxLength":500,"minLength":3,"title":"Evaluation Rule","description":"The evaluation rule value for this siteauditcheckspecification.","examples":["Example evaluation rule"]},"cap_dependencies":{"items":{"type":"string","enum":["tier0","tier1","tier2"]},"type":"array","maxItems":3,"title":"Cap Dependencies","description":"The cap dependencies value for this siteauditcheckspecification.","examples":[["tier0"]]}},"additionalProperties":false,"type":"object","required":["check","source_check","category","score_impact","evaluation_rule","cap_dependencies"],"title":"SiteAuditCheckSpecification","description":"Structured siteauditcheckspecification data exposed by the public API.","examples":[{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]}]},"SiteAuditCheckSuite":{"properties":{"profile":{"type":"string","const":"aeo_site_readiness_29","title":"Profile","description":"The profile value for this siteauditchecksuite."},"profile_version":{"type":"string","const":"2026-07-13","title":"Profile Version","description":"The profile version value for this siteauditchecksuite."},"source_derived":{"type":"boolean","const":true,"title":"Source Derived","description":"The source derived value for this siteauditchecksuite."},"total_checks":{"type":"integer","const":29,"title":"Total Checks","description":"The total checks value for this siteauditchecksuite."},"total_score_impact":{"type":"integer","const":201,"title":"Total Score Impact","description":"The total score impact value for this siteauditchecksuite."},"category_counts":{"$ref":"#/components/schemas/SiteAuditCategoryCounts","description":"The category counts value for this siteauditchecksuite.","examples":[{"technical":16,"structured_data":6,"ai_crawler":4,"authority":3}]},"checks":{"items":{"$ref":"#/components/schemas/SiteAuditCheckSpecification"},"type":"array","maxItems":29,"minItems":29,"title":"Checks","description":"The checks value for this siteauditchecksuite.","examples":[[{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]}]]}},"additionalProperties":false,"type":"object","required":["profile","profile_version","source_derived","total_checks","total_score_impact","category_counts","checks"],"title":"SiteAuditCheckSuite","description":"Structured siteauditchecksuite data exposed by the public API.","examples":[{"profile":"aeo_site_readiness_29","profile_version":"2026-07-13","source_derived":true,"total_checks":29,"total_score_impact":201,"category_counts":{"technical":16,"structured_data":6,"ai_crawler":4,"authority":3},"checks":[{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]}]}]},"SiteAuditFetchPolicy":{"properties":{"scheme":{"type":"string","const":"https","title":"Scheme","description":"The scheme value for this siteauditfetchpolicy."},"port":{"type":"integer","const":443,"title":"Port","description":"The port value for this siteauditfetchpolicy."},"methods":{"items":{"type":"string","const":"GET"},"type":"array","maxItems":1,"minItems":1,"title":"Methods","description":"The methods value for this siteauditfetchpolicy.","examples":[["GET"]]},"resources":{"items":{"$ref":"#/components/schemas/FetchResourcePolicy"},"type":"array","maxItems":3,"minItems":3,"title":"Resources","description":"The resources value for this siteauditfetchpolicy.","examples":[[{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]},{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]},{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]}]]},"maximum_total_bytes":{"type":"integer","const":4718592,"title":"Maximum Total Bytes","description":"The maximum total bytes value for this siteauditfetchpolicy."},"request_timeout_seconds":{"type":"integer","const":10,"title":"Request Timeout Seconds","description":"The request timeout seconds value for this siteauditfetchpolicy."},"maximum_redirects":{"type":"integer","const":3,"title":"Maximum Redirects","description":"The maximum redirects value for this siteauditfetchpolicy."},"redirect_scope":{"type":"string","const":"same_origin","title":"Redirect Scope","description":"The redirect scope value for this siteauditfetchpolicy."},"public_dns_resolution_required_before_each_request":{"type":"boolean","const":true,"title":"Public Dns Resolution Required Before Each Request","description":"The public dns resolution required before each request value for this siteauditfetchpolicy."},"globally_routable_ip_required":{"type":"boolean","const":true,"title":"Globally Routable Ip Required","description":"The globally routable ip required value for this siteauditfetchpolicy."},"dns_rebinding_protection_required":{"type":"boolean","const":true,"title":"Dns Rebinding Protection Required","description":"The dns rebinding protection required value for this siteauditfetchpolicy."},"resolved_ip_pinning_required":{"type":"boolean","const":true,"title":"Resolved Ip Pinning Required","description":"The resolved ip pinning required value for this siteauditfetchpolicy."},"tls_certificate_verification_required":{"type":"boolean","const":true,"title":"Tls Certificate Verification Required","description":"The tls certificate verification required value for this siteauditfetchpolicy."},"credentials_accepted":{"type":"boolean","const":false,"title":"Credentials Accepted","description":"The credentials accepted value for this siteauditfetchpolicy."},"authorization_headers_sent":{"type":"boolean","const":false,"title":"Authorization Headers Sent","description":"The authorization headers sent value for this siteauditfetchpolicy."},"cookies_sent":{"type":"boolean","const":false,"title":"Cookies Sent","description":"The cookies sent value for this siteauditfetchpolicy."},"javascript_execution":{"type":"boolean","const":false,"title":"Javascript Execution","description":"The javascript execution value for this siteauditfetchpolicy."},"browser_execution":{"type":"boolean","const":false,"title":"Browser Execution","description":"The browser execution value for this siteauditfetchpolicy."},"linked_page_fetches":{"type":"boolean","const":false,"title":"Linked Page Fetches","description":"The linked page fetches value for this siteauditfetchpolicy."},"sub_sitemap_fetches":{"type":"boolean","const":false,"title":"Sub Sitemap Fetches","description":"The sub sitemap fetches value for this siteauditfetchpolicy."},"cross_origin_redirects":{"type":"boolean","const":false,"title":"Cross Origin Redirects","description":"The cross origin redirects value for this siteauditfetchpolicy."},"identifiable_user_agent_required":{"type":"boolean","const":true,"title":"Identifiable User Agent Required","description":"The identifiable user agent required value for this siteauditfetchpolicy."}},"additionalProperties":false,"type":"object","required":["scheme","port","methods","resources","maximum_total_bytes","request_timeout_seconds","maximum_redirects","redirect_scope","public_dns_resolution_required_before_each_request","globally_routable_ip_required","dns_rebinding_protection_required","resolved_ip_pinning_required","tls_certificate_verification_required","credentials_accepted","authorization_headers_sent","cookies_sent","javascript_execution","browser_execution","linked_page_fetches","sub_sitemap_fetches","cross_origin_redirects","identifiable_user_agent_required"],"title":"SiteAuditFetchPolicy","description":"Structured siteauditfetchpolicy data exposed by the public API.","examples":[{"scheme":"https","port":443,"methods":["GET"],"resources":[{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]},{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]},{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]}],"maximum_total_bytes":4718592,"request_timeout_seconds":10,"maximum_redirects":3,"redirect_scope":"same_origin","public_dns_resolution_required_before_each_request":true,"globally_routable_ip_required":true,"dns_rebinding_protection_required":true,"resolved_ip_pinning_required":true,"tls_certificate_verification_required":true,"credentials_accepted":false,"authorization_headers_sent":false,"cookies_sent":false,"javascript_execution":false,"browser_execution":false,"linked_page_fetches":false,"sub_sitemap_fetches":false,"cross_origin_redirects":false,"identifiable_user_agent_required":true}]},"SiteAuditInterpretationPolicy":{"properties":{"heuristic_readiness_only":{"type":"boolean","const":true,"title":"Heuristic Readiness Only","description":"The heuristic readiness only value for this siteauditinterpretationpolicy."},"proves_indexing":{"type":"boolean","const":false,"title":"Proves Indexing","description":"The proves indexing value for this siteauditinterpretationpolicy."},"proves_ranking":{"type":"boolean","const":false,"title":"Proves Ranking","description":"The proves ranking value for this siteauditinterpretationpolicy."},"proves_ai_citation":{"type":"boolean","const":false,"title":"Proves Ai Citation","description":"The proves ai citation value for this siteauditinterpretationpolicy."},"proves_crawler_reachability":{"type":"boolean","const":false,"title":"Proves Crawler Reachability","description":"The proves crawler reachability value for this siteauditinterpretationpolicy."},"robots_rules_are_access_authorization":{"type":"boolean","const":false,"title":"Robots Rules Are Access Authorization","description":"The robots rules are access authorization value for this siteauditinterpretationpolicy."},"crawler_registry_revalidation_required":{"type":"boolean","const":true,"title":"Crawler Registry Revalidation Required","description":"The crawler registry revalidation required value for this siteauditinterpretationpolicy."}},"additionalProperties":false,"type":"object","required":["heuristic_readiness_only","proves_indexing","proves_ranking","proves_ai_citation","proves_crawler_reachability","robots_rules_are_access_authorization","crawler_registry_revalidation_required"],"title":"SiteAuditInterpretationPolicy","description":"Structured siteauditinterpretationpolicy data exposed by the public API.","examples":[{"heuristic_readiness_only":true,"proves_indexing":false,"proves_ranking":false,"proves_ai_citation":false,"proves_crawler_reachability":false,"robots_rules_are_access_authorization":false,"crawler_registry_revalidation_required":true}]},"SiteAuditPolicyVersion":{"type":"string","enum":["2026-07-13"],"title":"SiteAuditPolicyVersion","description":"Readable/replayable policies; append versions, never replace them.","examples":["2026-07-13"]},"SiteAuditSchemaVersion":{"type":"string","enum":["2026-07-13"],"title":"SiteAuditSchemaVersion","description":"Readable historical response schemas; append versions, never replace them.","examples":["2026-07-13"]},"SiteAuditScorePolicy":{"properties":{"maximum_score":{"type":"integer","const":100,"title":"Maximum Score","description":"The maximum score value for this siteauditscorepolicy."},"base_score_formula":{"type":"string","const":"weighted_severity_credit_percent","title":"Base Score Formula","description":"The base score formula value for this siteauditscorepolicy."},"final_score_formula":{"type":"string","const":"minimum_of_base_score_and_all_tier_caps","title":"Final Score Formula","description":"The final score formula value for this siteauditscorepolicy."},"rounding":{"type":"string","const":"nearest_tenth","title":"Rounding","description":"The rounding value for this siteauditscorepolicy."},"severity_credit":{"$ref":"#/components/schemas/SeverityCreditPolicy","description":"The severity credit value for this siteauditscorepolicy.","examples":[{"passed":1.0,"notice":0.7,"warning":0.3,"error":0.0}]},"cap_rules":{"items":{"$ref":"#/components/schemas/ScoreCapRule"},"type":"array","maxItems":9,"minItems":9,"title":"Cap Rules","description":"The cap rules value for this siteauditscorepolicy.","examples":[[{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5}]]},"grade_bands":{"items":{"$ref":"#/components/schemas/ScoreGradeBand"},"type":"array","maxItems":6,"minItems":6,"title":"Grade Bands","description":"The grade bands value for this siteauditscorepolicy.","examples":[[{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0}]]},"visibility_bands":{"items":{"$ref":"#/components/schemas/ScoreVisibilityBand"},"type":"array","maxItems":5,"minItems":5,"title":"Visibility Bands","description":"The visibility bands value for this siteauditscorepolicy.","examples":[[{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0}]]}},"additionalProperties":false,"type":"object","required":["maximum_score","base_score_formula","final_score_formula","rounding","severity_credit","cap_rules","grade_bands","visibility_bands"],"title":"SiteAuditScorePolicy","description":"Structured siteauditscorepolicy data exposed by the public API.","examples":[{"maximum_score":100,"base_score_formula":"weighted_severity_credit_percent","final_score_formula":"minimum_of_base_score_and_all_tier_caps","rounding":"nearest_tenth","severity_credit":{"passed":1.0,"notice":0.7,"warning":0.3,"error":0.0},"cap_rules":[{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5}],"grade_bands":[{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0}],"visibility_bands":[{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0}]}]},"SiteAuditSpecificationCreateIn":{"properties":{"key":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","title":"Key","description":"The key value for this siteauditspecificationcreatein.","examples":["example-key"]},"target":{"$ref":"#/components/schemas/SiteAuditTargetIn","description":"The target value for this siteauditspecificationcreatein.","examples":[{"domain":"Example domain","relationship":"owned_or_operated","authorization_attested":true}]},"check_profile":{"type":"string","const":"aeo_site_readiness_29","title":"Check Profile","description":"The check profile value for this siteauditspecificationcreatein."},"expected_policy_version":{"$ref":"#/components/schemas/SiteAuditPolicyVersion","description":"The expected policy version value for this siteauditspecificationcreatein.","examples":["2026-07-13"]},"reason":{"type":"string","maxLength":500,"minLength":3,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"Reason","description":"The reason value for this siteauditspecificationcreatein.","examples":["Example value"]}},"additionalProperties":false,"type":"object","required":["key","target","check_profile","expected_policy_version","reason"],"title":"SiteAuditSpecificationCreateIn","description":"Freeze an authorized future audit plan; no content, credentials, or URL is accepted.","examples":[{"key":"example-key","target":{"domain":"Example domain","relationship":"owned_or_operated","authorization_attested":true},"check_profile":"aeo_site_readiness_29","expected_policy_version":"2026-07-13","reason":"Example value"}]},"SiteAuditSpecificationListOut":{"properties":{"specifications":{"items":{"$ref":"#/components/schemas/SiteAuditSpecificationOut"},"type":"array","title":"Specifications","description":"The specifications value for this siteauditspecificationlistout.","examples":[[{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"siteaudit_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","target":{"domain":"Example domain","origin":"https://example.com","relationship":"owned_or_operated","authorization_attested":true,"root_path":"/"},"check_profile":"aeo_site_readiness_29","check_suite":{"profile":"aeo_site_readiness_29","profile_version":"2026-07-13","source_derived":true,"total_checks":29,"total_score_impact":201,"category_counts":{"technical":16,"structured_data":6,"ai_crawler":4,"authority":3},"checks":[{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]}]},"crawler_registry":{"version":"2026-07-13","revalidation_required_before_execution":true,"robots_standard":"RFC 9309","official_standard_url":"https://example.com","longest_match_required":true,"matching_groups_must_be_merged":true,"robots_rules_are_authorization":false,"identities":[{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false}]},"fetch_policy":{"scheme":"https","port":443,"methods":["GET"],"resources":[{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]},{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]},{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]}],"maximum_total_bytes":4718592,"request_timeout_seconds":10,"maximum_redirects":3,"redirect_scope":"same_origin","public_dns_resolution_required_before_each_request":true,"globally_routable_ip_required":true,"dns_rebinding_protection_required":true,"resolved_ip_pinning_required":true,"tls_certificate_verification_required":true,"credentials_accepted":false,"authorization_headers_sent":false,"cookies_sent":false,"javascript_execution":false,"browser_execution":false,"linked_page_fetches":false,"sub_sitemap_fetches":false,"cross_origin_redirects":false,"identifiable_user_agent_required":true},"score_policy":{"maximum_score":100,"base_score_formula":"weighted_severity_credit_percent","final_score_formula":"minimum_of_base_score_and_all_tier_caps","rounding":"nearest_tenth","severity_credit":{"passed":1.0,"notice":0.7,"warning":0.3,"error":0.0},"cap_rules":[{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5}],"grade_bands":[{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0}],"visibility_bands":[{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0}]},"interpretation_policy":{"heuristic_readiness_only":true,"proves_indexing":false,"proves_ranking":false,"proves_ai_citation":false,"proves_crawler_reachability":false,"robots_rules_are_access_authorization":false,"crawler_registry_revalidation_required":true},"policy_version":"2026-07-13","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"dns_queries_made":0,"http_requests_made":0,"html_requests_made":0,"robots_requests_made":0,"sitemap_requests_made":0,"redirects_followed":0,"bytes_received":0,"pages_fetched":0,"checks_evaluated":0,"audits_run":0,"scores_computed":0,"model_requests_made":0,"search_requests_made":0,"content_stored":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}]]},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"The total value for this siteauditspecificationlistout.","examples":[0]},"limit":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Limit","description":"The limit value for this siteauditspecificationlistout.","examples":[1]},"offset":{"type":"integer","maximum":10000.0,"minimum":0.0,"title":"Offset","description":"The offset value for this siteauditspecificationlistout.","examples":[0]},"availability":{"type":"string","const":"contract_only","title":"Availability","description":"The availability value for this siteauditspecificationlistout."},"execution_available":{"type":"boolean","const":false,"title":"Execution Available","description":"The execution available value for this siteauditspecificationlistout."},"http_requests_made":{"type":"integer","const":0,"title":"Http Requests Made","description":"The http requests made value for this siteauditspecificationlistout."},"audits_run":{"type":"integer","const":0,"title":"Audits Run","description":"The audits run value for this siteauditspecificationlistout."}},"additionalProperties":false,"type":"object","required":["specifications","total","limit","offset","availability","execution_available","http_requests_made","audits_run"],"title":"SiteAuditSpecificationListOut","description":"Structured siteauditspecificationlistout data exposed by the public API.","examples":[{"specifications":[{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"siteaudit_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","target":{"domain":"Example domain","origin":"https://example.com","relationship":"owned_or_operated","authorization_attested":true,"root_path":"/"},"check_profile":"aeo_site_readiness_29","check_suite":{"profile":"aeo_site_readiness_29","profile_version":"2026-07-13","source_derived":true,"total_checks":29,"total_score_impact":201,"category_counts":{"technical":16,"structured_data":6,"ai_crawler":4,"authority":3},"checks":[{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]}]},"crawler_registry":{"version":"2026-07-13","revalidation_required_before_execution":true,"robots_standard":"RFC 9309","official_standard_url":"https://example.com","longest_match_required":true,"matching_groups_must_be_merged":true,"robots_rules_are_authorization":false,"identities":[{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false}]},"fetch_policy":{"scheme":"https","port":443,"methods":["GET"],"resources":[{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]},{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]},{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]}],"maximum_total_bytes":4718592,"request_timeout_seconds":10,"maximum_redirects":3,"redirect_scope":"same_origin","public_dns_resolution_required_before_each_request":true,"globally_routable_ip_required":true,"dns_rebinding_protection_required":true,"resolved_ip_pinning_required":true,"tls_certificate_verification_required":true,"credentials_accepted":false,"authorization_headers_sent":false,"cookies_sent":false,"javascript_execution":false,"browser_execution":false,"linked_page_fetches":false,"sub_sitemap_fetches":false,"cross_origin_redirects":false,"identifiable_user_agent_required":true},"score_policy":{"maximum_score":100,"base_score_formula":"weighted_severity_credit_percent","final_score_formula":"minimum_of_base_score_and_all_tier_caps","rounding":"nearest_tenth","severity_credit":{"passed":1.0,"notice":0.7,"warning":0.3,"error":0.0},"cap_rules":[{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5}],"grade_bands":[{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0}],"visibility_bands":[{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0}]},"interpretation_policy":{"heuristic_readiness_only":true,"proves_indexing":false,"proves_ranking":false,"proves_ai_citation":false,"proves_crawler_reachability":false,"robots_rules_are_access_authorization":false,"crawler_registry_revalidation_required":true},"policy_version":"2026-07-13","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"dns_queries_made":0,"http_requests_made":0,"html_requests_made":0,"robots_requests_made":0,"sitemap_requests_made":0,"redirects_followed":0,"bytes_received":0,"pages_fetched":0,"checks_evaluated":0,"audits_run":0,"scores_computed":0,"model_requests_made":0,"search_requests_made":0,"content_stored":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}],"total":0,"limit":1,"offset":0,"availability":"contract_only","execution_available":false,"http_requests_made":0,"audits_run":0}]},"SiteAuditSpecificationOut":{"properties":{"schema_version":{"$ref":"#/components/schemas/SiteAuditSchemaVersion","description":"The schema version value for this siteauditspecificationout.","examples":["2026-07-13"]},"status":{"type":"string","const":"specified","title":"Status","description":"The status value for this siteauditspecificationout."},"availability":{"type":"string","const":"contract_only","title":"Availability","description":"The availability value for this siteauditspecificationout."},"id":{"type":"string","pattern":"^siteaudit_[a-f0-9]{24}$","title":"Id","description":"The id value for this siteauditspecificationout.","examples":["siteaudit_aaaaaaaaaaaaaaaaaaaaaaaa"]},"idempotent_replay":{"type":"boolean","title":"Idempotent Replay","description":"The idempotent replay value for this siteauditspecificationout.","examples":[true]},"key":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","title":"Key","description":"The key value for this siteauditspecificationout.","examples":["example-key"]},"project_id":{"type":"string","pattern":"^proj_[a-f0-9]{24}$","title":"Project Id","description":"The project id value for this siteauditspecificationout.","examples":["proj_aaaaaaaaaaaaaaaaaaaaaaaa"]},"environment":{"type":"string","enum":["live","test"],"title":"Environment","description":"The environment value for this siteauditspecificationout.","examples":["live"]},"target":{"$ref":"#/components/schemas/SiteAuditTargetOut","description":"The target value for this siteauditspecificationout.","examples":[{"domain":"Example domain","origin":"https://example.com","relationship":"owned_or_operated","authorization_attested":true,"root_path":"/"}]},"check_profile":{"$ref":"#/components/schemas/SiteAuditCheckProfile","description":"The check profile value for this siteauditspecificationout.","examples":["aeo_site_readiness_29"]},"check_suite":{"$ref":"#/components/schemas/SiteAuditCheckSuite","description":"The check suite value for this siteauditspecificationout.","examples":[{"profile":"aeo_site_readiness_29","profile_version":"2026-07-13","source_derived":true,"total_checks":29,"total_score_impact":201,"category_counts":{"technical":16,"structured_data":6,"ai_crawler":4,"authority":3},"checks":[{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]}]}]},"crawler_registry":{"$ref":"#/components/schemas/CrawlerRegistry","description":"The crawler registry value for this siteauditspecificationout.","examples":[{"version":"2026-07-13","revalidation_required_before_execution":true,"robots_standard":"RFC 9309","official_standard_url":"https://example.com","longest_match_required":true,"matching_groups_must_be_merged":true,"robots_rules_are_authorization":false,"identities":[{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false}]}]},"fetch_policy":{"$ref":"#/components/schemas/SiteAuditFetchPolicy","description":"The fetch policy value for this siteauditspecificationout.","examples":[{"scheme":"https","port":443,"methods":["GET"],"resources":[{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]},{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]},{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]}],"maximum_total_bytes":4718592,"request_timeout_seconds":10,"maximum_redirects":3,"redirect_scope":"same_origin","public_dns_resolution_required_before_each_request":true,"globally_routable_ip_required":true,"dns_rebinding_protection_required":true,"resolved_ip_pinning_required":true,"tls_certificate_verification_required":true,"credentials_accepted":false,"authorization_headers_sent":false,"cookies_sent":false,"javascript_execution":false,"browser_execution":false,"linked_page_fetches":false,"sub_sitemap_fetches":false,"cross_origin_redirects":false,"identifiable_user_agent_required":true}]},"score_policy":{"$ref":"#/components/schemas/SiteAuditScorePolicy","description":"The score policy value for this siteauditspecificationout.","examples":[{"maximum_score":100,"base_score_formula":"weighted_severity_credit_percent","final_score_formula":"minimum_of_base_score_and_all_tier_caps","rounding":"nearest_tenth","severity_credit":{"passed":1.0,"notice":0.7,"warning":0.3,"error":0.0},"cap_rules":[{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5}],"grade_bands":[{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0}],"visibility_bands":[{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0}]}]},"interpretation_policy":{"$ref":"#/components/schemas/SiteAuditInterpretationPolicy","description":"The interpretation policy value for this siteauditspecificationout.","examples":[{"heuristic_readiness_only":true,"proves_indexing":false,"proves_ranking":false,"proves_ai_citation":false,"proves_crawler_reachability":false,"robots_rules_are_access_authorization":false,"crawler_registry_revalidation_required":true}]},"policy_version":{"$ref":"#/components/schemas/SiteAuditPolicyVersion","description":"The policy version value for this siteauditspecificationout.","examples":["2026-07-13"]},"specification_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","title":"Specification Hash","description":"The specification hash value for this siteauditspecificationout.","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]},"reason":{"type":"string","maxLength":500,"minLength":3,"pattern":"^[^\\x00-\\x1f\\x7f]+$","title":"Reason","description":"The reason value for this siteauditspecificationout.","examples":["Example value"]},"execution_available":{"type":"boolean","const":false,"title":"Execution Available","description":"The execution available value for this siteauditspecificationout."},"execution_authorized":{"type":"boolean","const":false,"title":"Execution Authorized","description":"The execution authorized value for this siteauditspecificationout."},"dns_queries_made":{"type":"integer","const":0,"title":"Dns Queries Made","description":"The dns queries made value for this siteauditspecificationout."},"http_requests_made":{"type":"integer","const":0,"title":"Http Requests Made","description":"The http requests made value for this siteauditspecificationout."},"html_requests_made":{"type":"integer","const":0,"title":"Html Requests Made","description":"The html requests made value for this siteauditspecificationout."},"robots_requests_made":{"type":"integer","const":0,"title":"Robots Requests Made","description":"The robots requests made value for this siteauditspecificationout."},"sitemap_requests_made":{"type":"integer","const":0,"title":"Sitemap Requests Made","description":"The sitemap requests made value for this siteauditspecificationout."},"redirects_followed":{"type":"integer","const":0,"title":"Redirects Followed","description":"The redirects followed value for this siteauditspecificationout."},"bytes_received":{"type":"integer","const":0,"title":"Bytes Received","description":"The bytes received value for this siteauditspecificationout."},"pages_fetched":{"type":"integer","const":0,"title":"Pages Fetched","description":"The pages fetched value for this siteauditspecificationout."},"checks_evaluated":{"type":"integer","const":0,"title":"Checks Evaluated","description":"The checks evaluated value for this siteauditspecificationout."},"audits_run":{"type":"integer","const":0,"title":"Audits Run","description":"The audits run value for this siteauditspecificationout."},"scores_computed":{"type":"integer","const":0,"title":"Scores Computed","description":"The scores computed value for this siteauditspecificationout."},"model_requests_made":{"type":"integer","const":0,"title":"Model Requests Made","description":"The model requests made value for this siteauditspecificationout."},"search_requests_made":{"type":"integer","const":0,"title":"Search Requests Made","description":"The search requests made value for this siteauditspecificationout."},"content_stored":{"type":"boolean","const":false,"title":"Content Stored","description":"The content stored value for this siteauditspecificationout."},"outbound_authorized":{"type":"boolean","const":false,"title":"Outbound Authorized","description":"The outbound authorized value for this siteauditspecificationout."},"crm_mutation_authorized":{"type":"boolean","const":false,"title":"Crm Mutation Authorized","description":"The crm mutation authorized value for this siteauditspecificationout."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"The created at value for this siteauditspecificationout.","examples":["2026-07-16T00:00:00Z"]}},"additionalProperties":false,"type":"object","required":["schema_version","status","availability","id","idempotent_replay","key","project_id","environment","target","check_profile","check_suite","crawler_registry","fetch_policy","score_policy","interpretation_policy","policy_version","specification_hash","reason","execution_available","execution_authorized","dns_queries_made","http_requests_made","html_requests_made","robots_requests_made","sitemap_requests_made","redirects_followed","bytes_received","pages_fetched","checks_evaluated","audits_run","scores_computed","model_requests_made","search_requests_made","content_stored","outbound_authorized","crm_mutation_authorized","created_at"],"title":"SiteAuditSpecificationOut","description":"Structured siteauditspecificationout data exposed by the public API.","examples":[{"schema_version":"2026-07-13","status":"specified","availability":"contract_only","id":"siteaudit_aaaaaaaaaaaaaaaaaaaaaaaa","idempotent_replay":true,"key":"example-key","project_id":"proj_aaaaaaaaaaaaaaaaaaaaaaaa","environment":"live","target":{"domain":"Example domain","origin":"https://example.com","relationship":"owned_or_operated","authorization_attested":true,"root_path":"/"},"check_profile":"aeo_site_readiness_29","check_suite":{"profile":"aeo_site_readiness_29","profile_version":"2026-07-13","source_derived":true,"total_checks":29,"total_score_impact":201,"category_counts":{"technical":16,"structured_data":6,"ai_crawler":4,"authority":3},"checks":[{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]},{"check":"title_tag","source_check":"Example source check","category":"technical","score_impact":1,"evaluation_rule":"Example evaluation rule","cap_dependencies":["tier0"]}]},"crawler_registry":{"version":"2026-07-13","revalidation_required_before_execution":true,"robots_standard":"RFC 9309","official_standard_url":"https://example.com","longest_match_required":true,"matching_groups_must_be_merged":true,"robots_rules_are_authorization":false,"identities":[{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false},{"check":"title_tag","provider":"OpenAI","product":"Example product","user_agent":"OAI-SearchBot","purpose":"search_index","official_documentation_url":"https://example.com","robots_txt_evaluation_only":true,"impersonation_authorized":false}]},"fetch_policy":{"scheme":"https","port":443,"methods":["GET"],"resources":[{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]},{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]},{"resource":"root_html","path":"/","maximum_bytes":1,"allowed_content_types":["Example allowed content types"]}],"maximum_total_bytes":4718592,"request_timeout_seconds":10,"maximum_redirects":3,"redirect_scope":"same_origin","public_dns_resolution_required_before_each_request":true,"globally_routable_ip_required":true,"dns_rebinding_protection_required":true,"resolved_ip_pinning_required":true,"tls_certificate_verification_required":true,"credentials_accepted":false,"authorization_headers_sent":false,"cookies_sent":false,"javascript_execution":false,"browser_execution":false,"linked_page_fetches":false,"sub_sitemap_fetches":false,"cross_origin_redirects":false,"identifiable_user_agent_required":true},"score_policy":{"maximum_score":100,"base_score_formula":"weighted_severity_credit_percent","final_score_formula":"minimum_of_base_score_and_all_tier_caps","rounding":"nearest_tenth","severity_credit":{"passed":1.0,"notice":0.7,"warning":0.3,"error":0.0},"cap_rules":[{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5},{"tier":"tier0","condition":"Example condition","maximum_score":5}],"grade_bands":[{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0},{"grade":"A+","minimum_score":0,"maximum_score":0}],"visibility_bands":[{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0},{"band":"Excellent","minimum_score":0,"maximum_score":0}]},"interpretation_policy":{"heuristic_readiness_only":true,"proves_indexing":false,"proves_ranking":false,"proves_ai_citation":false,"proves_crawler_reachability":false,"robots_rules_are_access_authorization":false,"crawler_registry_revalidation_required":true},"policy_version":"2026-07-13","specification_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","reason":"Example value","execution_available":false,"execution_authorized":false,"dns_queries_made":0,"http_requests_made":0,"html_requests_made":0,"robots_requests_made":0,"sitemap_requests_made":0,"redirects_followed":0,"bytes_received":0,"pages_fetched":0,"checks_evaluated":0,"audits_run":0,"scores_computed":0,"model_requests_made":0,"search_requests_made":0,"content_stored":false,"outbound_authorized":false,"crm_mutation_authorized":false,"created_at":"2026-07-16T00:00:00Z"}]},"SiteAuditTargetIn":{"properties":{"domain":{"type":"string","maxLength":253,"minLength":4,"title":"Domain","description":"The domain value for this siteaudittargetin.","examples":["Example domain"]},"relationship":{"$ref":"#/components/schemas/SiteRelationship","description":"The relationship value for this siteaudittargetin.","examples":["owned_or_operated"]},"authorization_attested":{"type":"boolean","const":true,"title":"Authorization Attested","description":"The authorization attested value for this siteaudittargetin."}},"additionalProperties":false,"type":"object","required":["domain","relationship","authorization_attested"],"title":"SiteAuditTargetIn","description":"Name one authorized HTTPS host without accepting an arbitrary URL or path.","examples":[{"domain":"Example domain","relationship":"owned_or_operated","authorization_attested":true}]},"SiteAuditTargetOut":{"properties":{"domain":{"type":"string","maxLength":253,"minLength":4,"title":"Domain","description":"The domain value for this siteaudittargetout.","examples":["Example domain"]},"origin":{"type":"string","minLength":1,"format":"uri","title":"Origin","description":"The origin value for this siteaudittargetout.","examples":["https://example.com"]},"relationship":{"$ref":"#/components/schemas/SiteRelationship","description":"The relationship value for this siteaudittargetout.","examples":["owned_or_operated"]},"authorization_attested":{"type":"boolean","const":true,"title":"Authorization Attested","description":"The authorization attested value for this siteaudittargetout."},"root_path":{"type":"string","const":"/","title":"Root Path","description":"The root path value for this siteaudittargetout."}},"additionalProperties":false,"type":"object","required":["domain","origin","relationship","authorization_attested","root_path"],"title":"SiteAuditTargetOut","description":"Structured siteaudittargetout data exposed by the public API.","examples":[{"domain":"Example domain","origin":"https://example.com","relationship":"owned_or_operated","authorization_attested":true,"root_path":"/"}]},"SiteRelationship":{"type":"string","enum":["owned_or_operated","customer_authorized"],"title":"SiteRelationship","description":"Structured siterelationship data exposed by the public API.","examples":["owned_or_operated"]},"SourceAccessMode":{"type":"string","enum":["anonymous_public_snapshot","anonymous_public_api","credentialed_public_api","downloaded_public_snapshot"],"title":"SourceAccessMode","description":"Structured sourceaccessmode data exposed by the public API.","examples":["anonymous_public_snapshot"]},"TargetIndustry":{"type":"string","enum":["ai_ml","data_analytics","developer_tools","ecommerce","enterprise_software","fintech","healthcare","saas"],"title":"TargetIndustry","description":"The closed ProspectKit industry choices, normalized for stable contracts.","examples":["ai_ml"]},"TargetSeniority":{"type":"string","enum":["c_suite","director","individual_contributor","manager","vp"],"title":"TargetSeniority","description":"Structured targetseniority data exposed by the public API.","examples":["c_suite"]},"TemplateGenerationOptions":{"properties":{"tone":{"type":"string","enum":["direct","warm","consultative","technical"],"title":"Tone","default":"direct","description":"The tone value for this templategenerationoptions."},"locale":{"anyOf":[{"type":"string","maxLength":80,"minLength":2},{"type":"null"}],"title":"Locale","description":"The locale value for this templategenerationoptions.","examples":["Example locale"]},"max_words":{"type":"integer","maximum":120.0,"minimum":50.0,"title":"Max Words","default":90,"description":"The max words value for this templategenerationoptions."},"max_links":{"type":"integer","maximum":1.0,"minimum":0.0,"title":"Max Links","default":0,"description":"The max links value for this templategenerationoptions."},"allowed_claims":{"items":{"type":"string","maxLength":500,"minLength":1},"type":"array","maxItems":20,"title":"Allowed Claims","description":"The allowed claims value for this templategenerationoptions.","examples":[["Example allowed claims"]]},"forbidden_claims":{"items":{"type":"string","maxLength":500,"minLength":1},"type":"array","maxItems":20,"title":"Forbidden Claims","description":"The forbidden claims value for this templategenerationoptions.","examples":[["Example forbidden claims"]]},"preferred_terms":{"items":{"type":"string","maxLength":500,"minLength":1},"type":"array","maxItems":20,"title":"Preferred Terms","description":"The preferred terms value for this templategenerationoptions.","examples":[["Example preferred terms"]]},"forbidden_terms":{"items":{"type":"string","maxLength":500,"minLength":1},"type":"array","maxItems":20,"title":"Forbidden Terms","description":"The forbidden terms value for this templategenerationoptions.","examples":[["Example forbidden terms"]]},"notes":{"anyOf":[{"type":"string","maxLength":4000,"minLength":1},{"type":"null"}],"title":"Notes","description":"The notes value for this templategenerationoptions.","examples":["Example notes"]}},"additionalProperties":false,"type":"object","title":"TemplateGenerationOptions","description":"Optional copy controls; defaults follow the repository's sales-email research.","examples":[{}]},"TextInline":{"properties":{"kind":{"type":"string","const":"text","title":"Kind","description":"The kind value for this textinline."},"text":{"type":"string","maxLength":1000,"minLength":1,"title":"Text","description":"The text value for this textinline.","examples":["Example text"]}},"additionalProperties":false,"type":"object","required":["kind","text"],"title":"TextInline","description":"Structured textinline data exposed by the public API.","examples":[{"kind":"text","text":"Example text"}]},"Typeface":{"properties":{"role":{"type":"string","maxLength":120,"title":"Role","description":"The role value for this typeface.","examples":["Example role"]},"family":{"type":"string","maxLength":160,"title":"Family","description":"The family value for this typeface.","examples":["Example family"]},"weights":{"items":{"type":"string"},"type":"array","maxItems":12,"title":"Weights","description":"The weights value for this typeface.","examples":[["Example weights"]]},"styles":{"items":{"type":"string"},"type":"array","maxItems":12,"title":"Styles","description":"The styles value for this typeface.","examples":[["Example styles"]]},"fallbacks":{"items":{"type":"string"},"type":"array","maxItems":10,"title":"Fallbacks","description":"The fallbacks value for this typeface.","examples":[["Example fallbacks"]]},"source_url":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Source Url","description":"The source url value for this typeface.","examples":["https://example.com"]},"font_faces":{"items":{"$ref":"#/components/schemas/FontFaceAsset"},"type":"array","maxItems":32,"title":"Font Faces","description":"The font faces value for this typeface.","examples":[[{"url":"https://example.com"}]]},"usage":{"type":"string","maxLength":800,"title":"Usage","description":"The usage value for this typeface.","examples":["Example usage"]},"source_ids":{"items":{"type":"string"},"type":"array","maxItems":10,"title":"Source Ids","description":"The source ids value for this typeface.","examples":[["Example source ids"]]}},"additionalProperties":false,"type":"object","required":["role","family","usage"],"title":"Typeface","description":"Structured typeface data exposed by the public API.","examples":[{"role":"Example role","family":"Example family","usage":"Example usage"}]},"VariableClassification":{"type":"string","enum":["recipient_personal","recipient_business","account","sender","system"],"title":"VariableClassification","description":"Structured variableclassification data exposed by the public API.","examples":["recipient_personal"]},"VariableDefinition":{"properties":{"key":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9]*)*$","title":"Key","description":"The key value for this variabledefinition.","examples":["contact.firstname"]},"classification":{"$ref":"#/components/schemas/VariableClassification","description":"The classification value for this variabledefinition.","examples":["recipient_personal"]},"required":{"type":"boolean","title":"Required","description":"The required value for this variabledefinition.","examples":[true]},"max_length":{"type":"integer","maximum":2000.0,"minimum":1.0,"title":"Max Length","description":"The max length value for this variabledefinition.","examples":[1]}},"additionalProperties":false,"type":"object","required":["key","classification","required","max_length"],"title":"VariableDefinition","description":"Structured variabledefinition data exposed by the public API.","examples":[{"key":"contact.firstname","classification":"recipient_personal","required":true,"max_length":1}]},"VariableInline":{"properties":{"kind":{"type":"string","const":"variable","title":"Kind","description":"The kind value for this variableinline."},"key":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9]*)*$","title":"Key","description":"The key value for this variableinline.","examples":["contact.firstname"]}},"additionalProperties":false,"type":"object","required":["kind","key"],"title":"VariableInline","description":"Structured variableinline data exposed by the public API.","examples":[{"kind":"variable","key":"contact.firstname"}]},"VisualDirection":{"properties":{"art_direction":{"anyOf":[{"type":"string","maxLength":1200},{"type":"null"}],"title":"Art Direction","description":"The art direction value for this visualdirection.","examples":["Example art direction"]},"photography":{"items":{"type":"string"},"type":"array","maxItems":16,"title":"Photography","description":"The photography value for this visualdirection.","examples":[["Example photography"]]},"illustration":{"items":{"type":"string"},"type":"array","maxItems":16,"title":"Illustration","description":"The illustration value for this visualdirection.","examples":[["Example illustration"]]},"iconography":{"items":{"type":"string"},"type":"array","maxItems":16,"title":"Iconography","description":"The iconography value for this visualdirection.","examples":[["Example iconography"]]},"composition":{"items":{"type":"string"},"type":"array","maxItems":16,"title":"Composition","description":"The composition value for this visualdirection.","examples":[["Example composition"]]},"motion":{"items":{"type":"string"},"type":"array","maxItems":12,"title":"Motion","description":"The motion value for this visualdirection.","examples":[["Example motion"]]},"do":{"items":{"type":"string"},"type":"array","maxItems":16,"title":"Do","description":"The do value for this visualdirection.","examples":[["Example do"]]},"dont":{"items":{"type":"string"},"type":"array","maxItems":16,"title":"Dont","description":"The dont value for this visualdirection.","examples":[["Example dont"]]}},"additionalProperties":false,"type":"object","title":"VisualDirection","description":"Structured visualdirection data exposed by the public API.","examples":[{}]},"VoiceTrait":{"properties":{"name":{"type":"string","maxLength":100,"title":"Name","description":"The name value for this voicetrait.","examples":["Example name"]},"description":{"type":"string","maxLength":500,"title":"Description","description":"The description value for this voicetrait.","examples":["Example description"]},"do":{"items":{"type":"string"},"type":"array","maxItems":10,"title":"Do","description":"The do value for this voicetrait.","examples":[["Example do"]]},"dont":{"items":{"type":"string"},"type":"array","maxItems":10,"title":"Dont","description":"The dont value for this voicetrait.","examples":[["Example dont"]]}},"additionalProperties":false,"type":"object","required":["name","description"],"title":"VoiceTrait","description":"Structured voicetrait data exposed by the public API.","examples":[{"name":"Example name","description":"Example description"}]},"app__data_intake_schema__RequiredConnectorCapability":{"type":"string","enum":["public-dataset-read","government-registry-read","file-ingest"],"title":"RequiredConnectorCapability","description":"Structured app  data intake schema  requiredconnectorcapability data exposed by the public API.","examples":["public-dataset-read"]},"app__enrichment_spec_schema__RequiredConnectorCapability":{"type":"string","enum":["people-enrich","web-fetch","email-verify"],"title":"RequiredConnectorCapability","description":"Structured app  enrichment spec schema  requiredconnectorcapability data exposed by the public API.","examples":["people-enrich"]},"app__routers__v1_offers__OfferCreateIn":{"properties":{"brand_profile_id":{"type":"string","maxLength":80,"title":"Brand Profile Id","description":"The brand profile id value for this app  routers  v1 offers  offercreatein.","examples":["Example brand profile id"]},"name":{"type":"string","maxLength":160,"title":"Name","description":"The name value for this app  routers  v1 offers  offercreatein.","examples":["Example name"]},"key":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Key","description":"The key value for this app  routers  v1 offers  offercreatein.","examples":["Example key"]},"description":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}],"title":"Description","description":"The description value for this app  routers  v1 offers  offercreatein.","examples":["Example description"]},"value_props":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":24},{"type":"null"}],"title":"Value Props","description":"The value props value for this app  routers  v1 offers  offercreatein.","examples":[["Example value props"]]},"proof_points":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":24},{"type":"null"}],"title":"Proof Points","description":"The proof points value for this app  routers  v1 offers  offercreatein.","examples":[["Example proof points"]]},"pricing_model":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}],"title":"Pricing Model","description":"The pricing model value for this app  routers  v1 offers  offercreatein.","examples":["Example pricing model"]},"icp":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Icp","description":"The icp value for this app  routers  v1 offers  offercreatein.","examples":[{}]},"stage_fit":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":10},{"type":"null"}],"title":"Stage Fit","description":"The stage fit value for this app  routers  v1 offers  offercreatein.","examples":[["Example stage fit"]]},"status":{"type":"string","title":"Status","default":"active","description":"The status value for this app  routers  v1 offers  offercreatein."}},"additionalProperties":false,"type":"object","required":["brand_profile_id","name"],"title":"OfferCreateIn","description":"Structured app  routers  v1 offers  offercreatein data exposed by the public API.","examples":[{"brand_profile_id":"Example brand profile id","name":"Example name"}]}},"securitySchemes":{"ProjectBearerAuth":{"type":"http","description":"Project-scoped Blackpearl API key.","scheme":"bearer","bearerFormat":"API key"}}},"tags":[{"name":"Connectors","description":"Inspect connector manifests and configured project connections without exposing secrets."},{"name":"Capabilities","description":"List the capabilities your organization is entitled to."},{"name":"Playbooks","description":"Generate stage-aware AI sales playbooks for a target account."},{"name":"Prospecting","description":"Discover and qualify evidence-backed prospects, then produce outreach drafts."},{"name":"Documents","description":"Company dossier and personalised sales collateral contracts with strict evidence provenance."},{"name":"API","description":""},{"name":"Campaigns","description":"The organizing GTM container relating brand, offer, audience, playbook and templates."},{"name":"Audiences","description":"Scored B2B audiences — cycle outputs with paginated candidates, powered by RTSA."},{"name":"Jobs","description":"Poll the status and result of asynchronous jobs."},{"name":"Usage","description":"Month-to-date consumption, spend and credit balance for your project."},{"name":"Account Coordination","description":"Assess multi-contact account conflicts from immutable Audience and Outcome evidence."},{"name":"Audience Snapshots","description":"Immutable reviewed snapshots that downstream specification contracts bind."},{"name":"Brands","description":"Research first-class brands and consume evidence-backed, versioned brand guidelines."},{"name":"Message Templates","description":"Version code-free outreach templates and render exact approval-ready artifacts — no send authority."},{"name":"Enrichment","description":"Contact/company enrichment field plans, including business-email discovery."},{"name":"Data Intake","description":"Register custom data-source plans: versions, bounded selections and field policies."},{"name":"Offers","description":"What you sell: value propositions, proof points, pricing model and stage fit."},{"name":"Professional Network","description":"Bind official Sales Navigator connections for audience import — no scraping, no messaging."},{"name":"Prospect Research","description":"Evidence-bound account research plans combining structured and unstructured sources under hard budgets."},{"name":"Outcomes","description":"The append-only feedback ledger: record real-world results, read insight aggregates, improve over time."},{"name":"Qualification Policies","description":"Immutable five-dimension qualification rubrics that keep prospect quality high."},{"name":"Site Intelligence","description":"Bounded, authorized website readiness audits over HTTPS origins."}],"servers":[{"url":"https://api.blackpearl.com"}]}