> ## Documentation Index > Fetch the complete documentation index at: https://docs.getsales.io/llms.txt > Use this file to discover all available pages before exploring further. # Create data source > Create an ingestion source into a table. `type` says who runs it and is required: the same Sales Navigator link is a valid ai_search and a valid sender_search, so a link's shape never decides. ai_search: exactly one of url, payload.prompt or payload.filters; the pool runs it for credits, no sender. sender_search: sender_profile_sid plus url, unless payload.surface is my_network or messenger; payload.repeat reruns it. post_engagement: sender_profile_sid plus a post, profile or company page link (preview_post_engagement reads it back first); payload.window, relevance, collect and repeat tune it; every person lands with what they did. find_people: payload.company_sids and/or company_filter, plus a prompt or filters; always people. webhook: payload.records_path; the answer carries ingest_url (the credential: rotate to revoke). csv is refused: upload it, then import_data_source. Refusals are 422, the reason in field_errors[field][0].rule: url needs_sender (only a Sales Navigator search runs on the pool: the rest is a sender_search), url post_engagement (a post link in a search kind), link_not_recognized, object_type or payload.target agreement, payload in, payload.collect required, and on sender_profile_sid linkedin_account_missing, sales_nav_required, recruiter_required or recruiter_signed_out. No dedup. When NOT: blocking identifiers (create_stoplist_entry); feeding people into outreach (workflow sources). Contract: - MCP tool `create_data_source`, registry package `mcp.playtables/data_sources`, mount `playtables.sources`. - Operation `create`, response envelope `create`. - Flags: none. ## OpenAPI ````yaml /api-reference/playtables/openapi.yaml post /api/data-sources openapi: 3.0.3 info: title: 'GetSales public contract: gs.service.playtables' description: >- The data platform and the outreach engine: tables of people and companies, their enrichment columns, cells and runs, the data sources that feed them, sender profiles, the stoplist, the activity feed, the credit ledger, and the multichannel workflows with their per-person journeys and tasks. GENERATED. This document is projected from the Zod MCP tool registry in `product/mcp/gs.mcp` (one tool per public endpoint, 1:1). Do not edit it by hand; edit the tool definition and regenerate with `pnpm openapi:public`. Surface: the public `/api` contract of `gs.service.playtables`, 142 operations. This is the only OpenAPI document the platform publishes. Internal (`/internal`) and health endpoints are deliberately absent: they are not part of any contract, they can change without notice, and the service source is their only description. Conventions: - Auth is a bearer JWT, optionally narrowed by the `Team-SID` header. - Every success body is an MCP envelope: `success: true` plus one typed `operation` shape (`search`, `get`, `create`, `update`, `delete`, `metrics`, `group_by`, `action`), and a `meta` block with `trace_id` for support. - Every failure is the same `McpError` envelope with a code from a fixed 16-code taxonomy, so a client maps errors once. - Lists page with `page_size` (0 to 500, default 50) plus an opaque forward `cursor`; `page_size: 0` returns counts only. - On `GET` and `DELETE`, object-valued query parameters (`filter`, `sort`) travel as JSON text and array-valued ones repeat as `name[]=value`. - The MCP-only `_meta` field (usage analytics) never reaches the backend and is not part of this contract. version: '1.0' contact: name: GetSales url: https://getsales.io email: support@getsales.io license: name: Proprietary url: https://getsales.io/terms servers: - url: https://beta.getsales.io/playtables/v1 description: >- Production (the gateway path on the beta ring; the origin is provisioned per DEPLOY_MAP.md) security: - BearerJwt: [] TeamSid: [] tags: - name: activities description: >- Registry package `mcp.playtables/activities`, served on MCP mount `playtables.journeys`. - name: activity_objects description: >- Registry package `mcp.playtables/activity_objects`, served on MCP mount `playtables.people`. - name: companies description: >- Registry package `mcp.playtables/companies`, served on MCP mount `playtables.people`. - name: credit_ledger_entries description: >- Registry package `mcp.playtables/credit_ledger_entries`, served on MCP mount `id.billing`. - name: data_source_items description: >- Registry package `mcp.playtables/data_source_items`, served on MCP mount `playtables.sources`. - name: data_sources description: >- Registry package `mcp.playtables/data_sources`, served on MCP mount `playtables.sources`. - name: notes description: >- Registry package `mcp.playtables/notes`, served on MCP mount `playtables.pipeline`. - name: people description: >- Registry package `mcp.playtables/people`, served on MCP mount `playtables.people`. - name: pipeline_stages description: >- Registry package `mcp.playtables/pipeline_stages`, served on MCP mount `playtables.pipeline`. - name: plays description: >- Registry package `mcp.playtables/plays`, served on MCP mount `playtables.pipeline`. - name: playtable_field_values description: >- Registry package `mcp.playtables/playtable_field_values`, served on MCP mount `playtables.columns`. - name: playtable_fields description: >- Registry package `mcp.playtables/playtable_fields`, served on MCP mount `playtables.columns`. - name: playtable_runs description: >- Registry package `mcp.playtables/playtable_runs`, served on MCP mount `playtables.columns`. - name: playtable_views description: >- Registry package `mcp.playtables/playtable_views`, served on MCP mount `playtables.tables`. - name: playtables description: >- Registry package `mcp.playtables/playtables`, served on MCP mount `playtables.tables`. - name: result_pages description: >- Registry package `mcp.playtables/result_pages`, served on MCP mount `playtables.tables`. - name: sender_profiles description: >- Registry package `mcp.playtables/sender_profiles`, served on MCP mount `playtables.sources`. - name: stoplist_entries description: >- Registry package `mcp.playtables/stoplist_entries`, served on MCP mount `playtables.stoplist`. - name: tags description: >- Registry package `mcp.playtables/tags`, served on MCP mount `playtables.pipeline`. - name: workflow_attachments description: >- Registry package `mcp.playtables/workflow_attachments`, served on MCP mount `playtables.workflows`. - name: workflow_records description: >- Registry package `mcp.playtables/workflow_records`, served on MCP mount `playtables.journeys`. - name: workflow_sources description: >- Registry package `mcp.playtables/workflow_sources`, served on MCP mount `playtables.workflows`. - name: workflow_tasks description: >- Registry package `mcp.playtables/workflow_tasks`, served on MCP mount `playtables.journeys`. - name: workflow_versions description: >- Registry package `mcp.playtables/workflow_versions`, served on MCP mount `playtables.workflows`. - name: workflows description: >- Registry package `mcp.playtables/workflows`, served on MCP mount `playtables.workflows`. paths: /api/data-sources: post: tags: - data_sources summary: Create data source description: >- Create an ingestion source into a table. `type` says who runs it and is required: the same Sales Navigator link is a valid ai_search and a valid sender_search, so a link's shape never decides. ai_search: exactly one of url, payload.prompt or payload.filters; the pool runs it for credits, no sender. sender_search: sender_profile_sid plus url, unless payload.surface is my_network or messenger; payload.repeat reruns it. post_engagement: sender_profile_sid plus a post, profile or company page link (preview_post_engagement reads it back first); payload.window, relevance, collect and repeat tune it; every person lands with what they did. find_people: payload.company_sids and/or company_filter, plus a prompt or filters; always people. webhook: payload.records_path; the answer carries ingest_url (the credential: rotate to revoke). csv is refused: upload it, then import_data_source. Refusals are 422, the reason in field_errors[field][0].rule: url needs_sender (only a Sales Navigator search runs on the pool: the rest is a sender_search), url post_engagement (a post link in a search kind), link_not_recognized, object_type or payload.target agreement, payload in, payload.collect required, and on sender_profile_sid linkedin_account_missing, sales_nav_required, recruiter_required or recruiter_signed_out. No dedup. When NOT: blocking identifiers (create_stoplist_entry); feeding people into outreach (workflow sources). Contract: - MCP tool `create_data_source`, registry package `mcp.playtables/data_sources`, mount `playtables.sources`. - Operation `create`, response envelope `create`. - Flags: none. operationId: create_data_source requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateDataSourceRequest' responses: '200': description: '`create` success envelope.' content: application/json: schema: $ref: '#/components/schemas/CreateDataSourceResponse' 4XX: $ref: '#/components/responses/McpClientError' 5XX: $ref: '#/components/responses/McpServerError' components: schemas: CreateDataSourceRequest: type: object description: Request body of `create_data_source`. properties: playtable_sid: type: string minLength: 18 maxLength: 18 pattern: ^pt_tb_ description: >- Target table (pt_tb_…) receiving promoted objects. Required for every kind. type: type: string enum: - ai_search - sender_search - post_engagement - find_people - csv - webhook description: >- Required. ai_search | sender_search | post_engagement | find_people | webhook. `csv` is accepted by the shape rule and then refused with the way in: upload the file through upload-csv, then confirm it with import_data_source. url: type: string maxLength: 2048 format: uri description: >- LinkedIn link of an ai_search, sender_search or post_engagement: /search/results, /sales/search, /sales/lists, /talent/search?searchHistoryId=, /mynetwork, /messaging; post_engagement: /posts, /feed/update, lnkd.in, /in/{slug}, /company/{slug}. object_type: type: string enum: - people - company description: >- What the rows become: people | company. Required for a description-mode ai_search. Elsewhere optional and checked for agreement with the link (or with the kind: find_people and webhook always bring people). name: type: string minLength: 1 maxLength: 255 description: >- Defaults from the kind and its link ("Sales Navigator saved search", "My network", "AI search: "). sender_profile_sid: type: string minLength: 18 maxLength: 18 pattern: ^ub_sp_ description: >- The sender profile whose own LinkedIn account collects (ub_sp_); required for sender_search and post_engagement, prohibited elsewhere. Must be live, hold a LinkedIn account and the licence the link needs (Sales Navigator, or an active Recruiter session). payload: type: object properties: prompt: type: string maxLength: 2000 description: >- ai_search, find_people. Who to find, in words. ai_search: a prompt that is only an http(s) link is read as the link. find_people: empty = everyone at each company. Planned into the search filter at the first collect; no filter from it = plan_failed. filters: type: object additionalProperties: {} description: >- ai_search, find_people. The by-params filter set plan_data_source_filters returns: it IS the plan, so planning is skipped (prompt may ride as the description). For find_people current companies are injected per anchor, never here. surface: type: string enum: - search - saved_search - list - post - my_network - messenger description: >- sender_search only. my_network (the profile's 1st-degree connections) or messenger (its conversation partners) is how a sender search runs WITHOUT a url. Sent with a url it must agree with what the link is (422 on payload.surface, rule agreement). repeat: type: string nullable: true enum: - hourly - daily - weekly - monthly description: >- sender_search, post_engagement. hourly | daily | weekly | monthly = run again at that interval, bringing what is new (a post engagement: new people on the post, or new posts in the window); null or absent = once. Pool kinds never repeat. target: type: string enum: - post - person - company description: >- post_engagement only. What the link must be: post | person | company; refused when the link is something else (422 on payload.target, rule agreement). Absent = read off the link. window: anyOf: - type: object properties: days: anyOf: - type: number enum: - 7 - type: number enum: - 30 - type: number enum: - 90 required: - days additionalProperties: false - type: object properties: since: type: string pattern: ^\d{4}-\d{2}-\d{2}$ required: - since additionalProperties: false description: >- post_engagement, a person or a company only: {days: 7 | 30 | 90} back from each run (default 30), or {since: "YYYY-MM-DD"} within the past year. On one post it is 422 rule prohibited. relevance: type: object nullable: true properties: prompt: type: string minLength: 1 maxLength: 2000 required: - prompt additionalProperties: false description: >- post_engagement only. The AI post filter: which posts count, in the user's words ("posts about outbound; skip job ads"). One llm.generate per 20 posts, billed as the source's check; a post it could not judge passes. null or absent = every post is walked. collect: type: object properties: reactions: type: boolean comments: type: boolean reposts: type: boolean additionalProperties: false description: >- post_engagement only. {reactions, comments, reposts}, each true or false; absent switches default to reactions and comments on, reposts off; all three off is 422 rule required. company_sids: type: array items: type: string minLength: 18 maxLength: 18 pattern: ^cr_co_ minItems: 1 maxItems: 500 description: >- find_people only; required there unless company_filter is given. The companies to find people at (cr_co_, from the companies grid), at most 500 per source: over the cap is 422 rule max. Grow the queue with add_companies_to_data_source. company_filter: type: object additionalProperties: {} description: >- find_people only. An account filter instead of (or with) company_sids: the search_companies filter object as is, resolved to sids at the call (a disqualified account is left out). No match and no sids is 422 rule required; past 500 matches 422 rule max. per_company_limit: type: integer minimum: 1 maximum: 25 description: >- find_people only. People taken per company (1..25); absent = the whole first search page (25). records_path: type: string description: >- webhook only. Where the array of records sits in an inbound body ("data.contacts"); absent = the body is the record or the array itself. description: >- The kind's own keys: ai_search {prompt | filters}, sender_search {surface, repeat}, post_engagement {target, window, relevance, collect, repeat}, find_people {company_sids, company_filter, per_company_limit, prompt, filters}, webhook {records_path}. field_mapping: type: array items: type: object properties: source: type: string minLength: 1 maxLength: 512 description: >- CSV column index as a string ("3") or JSON path into the webhook body ("contact.email"). target_kind: type: string enum: - people_attribute - company_attribute - field_slug description: people_attribute | company_attribute | field_slug. target: type: string minLength: 1 maxLength: 255 description: >- Attribute key (people / company) or a playtable field slug in the target table. name: type: string nullable: true minLength: 1 maxLength: 255 description: >- Display name for the column a field_slug target creates (the header renamed in the mapping UI); null = the CSV header names it. Ignored for the attribute kinds and for fields that already exist. required: - source - target_kind - target description: >- Optional override for type=webhook (absent = attribute auto-detect at promotion); prohibited for the three search kinds, whose collector emits the canonical parser shape. A csv source gets its mapping at import. tag_sids: type: array items: type: string minLength: 18 maxLength: 18 pattern: ^cr_tg_ description: Each tag must exist (cr_tg_…); applied to every promoted object. on_duplicate: type: string enum: - skip - move description: Default 'skip'. add_tags_to_duplicate: type: boolean description: Default false - merge tag_sids onto matched duplicates. qualify: type: object nullable: true properties: 'on': type: boolean description: >- The switch. `on` with no criterion is refused (422 on qualify.criterion, rule required_if). criterion: type: string nullable: true minLength: 1 maxLength: 2000 description: >- Who passes, in the user's words ("a decision maker at a marketing agency, not a freelancer"). Trimmed; null while the check is off. required: - 'on' - criterion additionalProperties: false description: >- The source gate, "Check on save": {on, criterion}. A closed object (an unknown key is 422 rule invalid_qualify); on with no words is refused. required: - playtable_sid - type CreateDataSourceResponse: type: object properties: success: type: boolean enum: - true operation: type: string enum: - create item: type: object properties: sid: type: string team_sid: type: string playtable_sid: type: string nullable: true description: >- pt_tb_… target table, required on every create; becomes null only when the target playtable is deleted (the source auto-pauses, status_reason=playtable_deleted). name: type: string description: >- min 1, max 255. Defaulted from the kind and its link when omitted on create ("Sales Navigator saved search", "My conversations", "AI search: CMOs in DACH"). type: type: string enum: - ai_search - sender_search - post_engagement - find_people - csv - webhook description: >- [ro] The source kind: ai_search | sender_search | post_engagement | find_people | csv | webhook. Immutable after create. object_type: type: string enum: - people - company description: >- What promoted items become: people | company. An input of create, not a derivation of type; [ro] once the source is past draft (a csv draft's import step may still change it). sender_profile_sid: type: string nullable: true description: >- ub_sp_… the sender profile whose own LinkedIn account collects. Required for type=sender_search and post_engagement, null for every other kind - see ./sender_profiles.md. ingest_key: type: string nullable: true description: >- type=webhook only: the 40-char capability secret in the ingest URL ({api_base}/external/ingest/{ingest_key}). Stored plaintext by design so the URL stays re-viewable; rotate-ingest-key revokes it. null for every other kind. payload: anyOf: - type: object properties: platform: type: string enum: - linkedin - sales_navigator - recruiter description: >- ai_search (link mode) and sender_search: which LinkedIn product the link opens in. surface: type: string enum: - search - saved_search - list - post - my_network - messenger description: >- ai_search (link mode) and sender_search: what kind of list the link is. repeat: type: string nullable: true enum: - hourly - daily - weekly - monthly description: >- sender_search, post_engagement: the rerun interval; absent or null = runs once. mode: type: string enum: - create - update description: 'csv: what the import does with its rows.' target: type: string enum: - post - person - company description: >- post_engagement: what the source watches; the axis beside it names it (post.urn, person.ln_nickname, or company.ln_nickname with ln_id, name and logo_url once the walk resolved the page). A link is never stored: rebuild it from the axis. window: anyOf: - type: object properties: days: anyOf: - type: number enum: - 7 - type: number enum: - 30 - type: number enum: - 90 required: - days additionalProperties: false - type: object properties: since: type: string pattern: ^\d{4}-\d{2}-\d{2}$ required: - since additionalProperties: false description: >- post_engagement, a person or a company: the window the posts are read from. relevance: type: object properties: prompt: type: string required: - prompt description: >- post_engagement: the AI post filter; absent = every post is walked. collect: type: object properties: reactions: type: boolean comments: type: boolean reposts: type: boolean additionalProperties: false description: 'post_engagement: the feeds the walk collects.' posts: type: array items: type: object properties: urn: type: string title: type: string published_at: type: string nullable: true verdict: type: string enum: - match - skip verdict_reason: type: string required: - urn description: >- post_engagement: the posts the walk read, newest first, each with its title (the first line), text, author, published_at, counts, the filter's verdict with the reason of a skip, and the walk's cursor per feed (feeds.reactors | comments | resharers: {cursor} or {done: true}). - type: array items: {} description: >- Kind-discriminated config JSON, validated per kind server-side. ai_search: prompt | url + platform + surface, filters + engine (the stored plan), plan_chips / plan_warnings, next_page / latest_page (the walk cursor), collect_error (what stopped the walk: kind transient | refused, http, code, reason, message, fields; with status_reason collect_failed | collect_interrupted). sender_search: url + platform + surface, repeat, and the collector's own cursor (next_page / latest_page for the Recruiter walker, poll_since / poll_cursor / poll_max for the network and inbox pollers; the bus-served surfaces keep none). find_people: company_sids, next_index, per_company_limit, prompt, filters + engine. csv: file_path, file_type, mode, total_rows, config, match. webhook: records_path. post_engagement (2026-10-28): target + post {urn} | person {ln_nickname; ln_id, ln_member_id, name once resolved} | company {ln_nickname, ln_id, name, logo_url}, window, relevance, collect, repeat, and the walk's own state: stage (posts | judge | engage | done), posts (what it read, with verdicts and feed cursors), cycle, next_page / latest_page, migrated_from on a row born as a search with a post link before the kind existed. field_mapping: type: array nullable: true items: type: object properties: source: type: string minLength: 1 maxLength: 512 description: >- CSV column index as a string ("3") or JSON path into the webhook body ("contact.email"). target_kind: type: string enum: - people_attribute - company_attribute - field_slug description: people_attribute | company_attribute | field_slug. target: type: string minLength: 1 maxLength: 255 description: >- Attribute key (people / company) or a playtable field slug in the target table. name: type: string nullable: true minLength: 1 maxLength: 255 description: >- Display name for the column a field_slug target creates (the header renamed in the mapping UI); null = the CSV header names it. Ignored for the attribute kinds and for fields that already exist. required: - source - target_kind - target description: >- source→target entries: set at import for csv (and may be []), an optional override for webhook (absent = attribute auto-detect at promotion), forbidden for the three search kinds (their collector emits the canonical parser shape). tag_sids: type: array nullable: true items: type: string description: >- cr_tg_… each - tags applied to every promoted object - see ./tags.md. qualify: type: object nullable: true properties: 'on': type: boolean description: >- The switch. `on` with no criterion is refused (422 on qualify.criterion, rule required_if). criterion: type: string nullable: true minLength: 1 maxLength: 2000 description: >- Who passes, in the user's words ("a decision maker at a marketing agency, not a freelancer"). Trimmed; null while the check is off. required: - 'on' - criterion additionalProperties: false description: >- The source gate, "Check on save": null = no check. The promotion reads it before a row is born (see ./data_source_items.md Lifecycle 6.5). on_duplicate: type: string enum: - skip - move description: Duplicate-person policy; default 'skip'. add_tags_to_duplicate: type: boolean description: Merge tag_sids onto matched duplicates; default false. status: type: string enum: - draft - active - paused - completed - failed status_reason: type: string nullable: true description: >- Reason token behind a paused or failed state (max 2048): playtable_deleted, sales_nav_required, recruiter_required, recruiter_reauth_required, executor_account_missing, plan_failed, collect_failed, collect_interrupted, post_unavailable (the post could not be read: deleted or private), target_not_found (no page at the slug), allowance_exhausted (the AI post filter ran out of credits; paused), … next_collect_at: type: string nullable: true description: >- ISO 8601 UTC - the collect clock of a search kind, advanced by checkpoints and the repeat interval. null for csv and webhook, and nulled on a bus-served sender search once its scrapes are provisioned (gtm-api owns the cadence from then on). created_by: type: object properties: actor_type: type: string enum: - user - support - api_key - system - agent actor_sid: type: string nullable: true team_sid: type: string actor_name: type: string nullable: true description: >- The OAuth client that acted ("Claude", "n8n"); null for a user, an API key or a system job. oauth_client_sid: type: string nullable: true description: The acting OAuth client (id_oc_*); null off the OAuth path. reason: type: string nullable: true description: >- Why a system actor wrote the row (snapshot_capture_job, ...); null otherwise. permissions: type: object additionalProperties: {} description: >- Internal audit context: the grant set the actor held at write time. Not a contract. cluster_id: type: integer nullable: true description: 'Internal audit context: the cluster that served the write.' trace_id: type: string nullable: true description: >- Internal audit context: the trace id of the request that wrote the row. required: - actor_type - actor_sid - team_sid - permissions deleted_by: type: object nullable: true properties: actor_type: type: string enum: - user - support - api_key - system - agent actor_sid: type: string nullable: true team_sid: type: string actor_name: type: string nullable: true description: >- The OAuth client that acted ("Claude", "n8n"); null for a user, an API key or a system job. oauth_client_sid: type: string nullable: true description: The acting OAuth client (id_oc_*); null off the OAuth path. reason: type: string nullable: true description: >- Why a system actor wrote the row (snapshot_capture_job, ...); null otherwise. permissions: type: object additionalProperties: {} description: >- Internal audit context: the grant set the actor held at write time. Not a contract. cluster_id: type: integer nullable: true description: 'Internal audit context: the cluster that served the write.' trace_id: type: string nullable: true description: >- Internal audit context: the trace id of the request that wrote the row. required: - actor_type - actor_sid - team_sid - permissions created_at: type: string updated_at: type: string deleted_at: type: string nullable: true required: - sid - team_sid - playtable_sid - name - type - object_type - sender_profile_sid - ingest_key - payload - field_mapping - tag_sids - qualify - on_duplicate - add_tags_to_duplicate - status - status_reason - next_collect_at - created_by - deleted_by - created_at - updated_at - deleted_at already_exists: type: boolean meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: string nullable: true description: >- The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: string nullable: true description: >- user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms ingest_url: type: string description: >- type=webhook only: {api_base}/external/ingest/{ingest_key} - the endpoint the customer CRM POSTs records to. The URL IS the credential: hand it to the user over a channel they trust, and rotate it to revoke. required: - success - operation - item - already_exists - meta McpError: type: object properties: success: type: boolean enum: - false error: type: object properties: code: type: string enum: - validation_failed - nothing_to_update - not_found - relation_not_found - invalid_transition - limit_exceeded - payment_required - duplicate_rejected - conflict - delete_blocked - unauthorized - forbidden - rate_limited - internal_error - service_unavailable - not_implemented message: type: string recoverable: type: boolean suggestion: type: string field_errors: type: object additionalProperties: type: array items: type: object properties: rule: type: string message: type: string required: - rule - message blockers: type: array items: type: object properties: type: type: string description: >- Machine-readable blocker type (active_flow, pending_tasks, …). severity: type: string enum: - hard - soft description: >- hard = external action required; soft = acknowledge is enough. description: type: string entity_sid: type: string nullable: true count: type: integer resolution: type: string description: 'Hard: tool name to call. Soft: code for acknowledge[].' resolution_hint: type: string required: - type - severity - description - entity_sid - resolution - resolution_hint context: type: object additionalProperties: {} required: - code - message - recoverable meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: string nullable: true description: >- The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: string nullable: true description: >- user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms required: - success - error responses: McpClientError: description: >- MCP error envelope. `error.code` is one of validation_failed, nothing_to_update, not_found, relation_not_found, invalid_transition, limit_exceeded, payment_required, duplicate_rejected, conflict, delete_blocked, unauthorized, forbidden, rate_limited, not_implemented. content: application/json: schema: $ref: '#/components/schemas/McpError' McpServerError: description: >- MCP error envelope with `error.code` internal_error or service_unavailable. content: application/json: schema: $ref: '#/components/schemas/McpError' securitySchemes: BearerJwt: type: http scheme: bearer bearerFormat: JWT description: >- Access token issued by gs.service.id. Its `access_identity` claim carries `team_sid`, `actor_sid` and `actor_type`, and that team scope is authoritative. TeamSid: type: apiKey in: header name: Team-SID description: >- Team scope for tokens that do not carry one. Ignored when the token already names a team. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.