{"openapi":"3.1.0","info":{"title":"PRESHos API","version":"1.0.0","summary":"Build on PRESHos: records, schema, relationships, comments, and search for every workspace object.","description":"The PRESHos API is one registry-driven surface over every object in a workspace — CRM objects, work items, business catalogs, and each tenant's custom objects. Discover a workspace's data model with `GET /v1/objects`, then use the same record endpoints for any object type.\n\n**Authentication.** Create a personal API key in PRESHos under **Settings → Developer** and send it as `Authorization: Bearer <key>`. A key acts as the user who created it: it can never do more than that user, and key scopes can restrict it further.\n\nGuides, changelog, and examples: https://developers.dev.preshos.com","contact":{"name":"PRESHos Developers","url":"https://developers.dev.preshos.com"}},"servers":[{"url":"https://api.dev.preshos.com/v1","description":"Production"}],"security":[{"ApiKey":[]}],"tags":[{"name":"Workspace","description":"The API key's identity, workspace members, and teams."},{"name":"Schema","description":"Discover object types, fields, relationships, and workflows for this workspace."},{"name":"Records","description":"Create, read, update, delete, search, aggregate, and batch-edit records of any object type."},{"name":"Relationships","description":"Discover and traverse relationships; link and unlink records."},{"name":"Comments","description":"Read and post record comments."},{"name":"Search","description":"Search across object types."}],"paths":{"/me":{"get":{"operationId":"getMe","tags":["Workspace"],"summary":"Identify the API key","description":"Returns the user the key acts as, its workspace, the key's scopes and expiry, and the rate limit. Use it to verify a key is working. Needs no scope.","parameters":[],"responses":{"200":{"description":"Key identity.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","email","title"]},"workspace":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"]},"api_key":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["personal","operational"]},"prefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","type","prefix","scopes","expires_at"]},"rate_limit":{"type":"object","properties":{"requests_per_minute":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["requests_per_minute"]}},"required":["user","workspace","api_key","rate_limit"]}},"required":["data"]},"example":{"data":{"user":{"id":23,"name":"Sam Rivera","email":"sam@example.com","title":"Operations Lead"},"workspace":{"id":9,"slug":"acme","name":"Acme Corp"},"api_key":{"id":"6f1c…","name":"CRM sync","type":"personal","prefix":"preshos_v1_Ab12Cd34Ef56","scopes":["records:read","records:write"],"expires_at":"2026-12-30T00:00:00.000Z"},"rate_limit":{"requests_per_minute":300}}}}}},"401":{"$ref":"#/components/responses/Error401"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}},"x-required-scopes":[],"x-preshos-annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true},"security":[{"ApiKey":[]}]}},"/users":{"get":{"operationId":"listUsers","tags":["Workspace"],"summary":"List workspace members","description":"Lists people in this workspace (agents excluded) with their teams. Use user ids for owner fields and mentions. Users who may not read the whole member directory see only themselves.\n\n**Required scopes:** `users:read`","parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":500}},{"name":"q","in":"query","required":false,"description":"Match on name or email.","schema":{"type":"string","maxLength":200}},{"name":"include_inactive","in":"query","required":false,"schema":{"default":"false","type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"Members.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/User"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]},"example":{"data":[{"id":17,"name":"Jordan Lee","email":"jordan@example.com","title":"Account Director","active":true,"teams":[{"id":3,"name":"Sales"}]}],"pagination":{"limit":50,"has_more":false,"next_cursor":null}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}},"x-required-scopes":["users:read"],"x-preshos-annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true},"security":[{"ApiKey":[]}]}},"/users/{user_id}":{"get":{"operationId":"getUser","tags":["Workspace"],"summary":"Retrieve a member","description":"Returns one workspace member by user id.\n\n**Required scopes:** `users:read`","parameters":[{"name":"user_id","in":"path","required":true,"description":"Workspace user id.","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"The member.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/User"}},"required":["data"]},"example":{"data":{"id":17,"name":"Jordan Lee","email":"jordan@example.com","title":"Account Director","active":true,"teams":[{"id":3,"name":"Sales"}]}}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}},"x-required-scopes":["users:read"],"x-preshos-annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true},"security":[{"ApiKey":[]}]}},"/teams":{"get":{"operationId":"listTeams","tags":["Workspace"],"summary":"List teams","description":"Lists the workspace's teams and their member ids (or only your own teams if you may not read all teams). Team membership determines \"team records\" access.\n\n**Required scopes:** `users:read`","parameters":[],"responses":{"200":{"description":"Teams.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Team"}}},"required":["data"]},"example":{"data":[{"id":3,"name":"Sales","description":"New business and renewals","member_ids":[17,23]}]}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}},"x-required-scopes":["users:read"],"x-preshos-annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true},"security":[{"ApiKey":[]}]}},"/objects":{"get":{"operationId":"listObjects","tags":["Schema"],"summary":"List object types","description":"Lists the object types available in this workspace that the key's user can read: CRM objects, work items, business catalogs, and every custom object. `capabilities` says what the object supports through the API; `permissions` is advisory and says what this user may do.\n\n**Required scopes:** `records:read`","parameters":[{"name":"include_unreadable","in":"query","required":false,"description":"Also return objects the user cannot read (default false).","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"Object types.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ObjectSummary"}}},"required":["data"]},"example":{"data":[{"object_type":"companies","name":"Companies","singular_name":"Company","description":"Customer and prospect organizations.","kind":"built_in","category":"crm","display_field":"name","capabilities":{"search":true,"create":true,"update":true,"delete":false},"permissions":{"create":{"allowed":true,"scopes":["owned_by_user"]},"read":{"allowed":true,"scopes":["org_wide"]},"update":{"allowed":true,"scopes":["owned_by_team"]},"delete":{"allowed":false,"scopes":[]}}}]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}},"x-required-scopes":["records:read"],"x-preshos-annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true},"security":[{"ApiKey":[]}]}},"/objects/{object_type}":{"get":{"operationId":"getObject","tags":["Schema"],"summary":"Describe an object type","description":"Returns the full contract for one object type in this workspace: every field the user may read (key, type, required, editable, options, validation), relationships, the status workflow, and — for work items — the active work-item types. For work items pass `work_item_type_id` to include that type's configured fields.\n\n**Required scopes:** `records:read`","parameters":[{"name":"object_type","in":"path","required":true,"description":"Object type id from `GET /v1/objects`, e.g. `companies`, `work-items`, or a custom object id.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,99}$"}},{"name":"work_item_type_id","in":"query","required":false,"description":"Work items only: include fields placed on this type.","schema":{"type":"string","maxLength":100}}],"responses":{"200":{"description":"The object definition.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ObjectDefinition"}},"required":["data"]},"example":{"data":{"object_type":"companies","name":"Companies","singular_name":"Company","description":"Customer and prospect organizations.","kind":"built_in","category":"crm","display_field":"name","capabilities":{"search":true,"create":true,"update":true,"delete":false},"permissions":{"create":{"allowed":true,"scopes":["owned_by_user"]},"read":{"allowed":true,"scopes":["org_wide"]},"update":{"allowed":true,"scopes":["owned_by_team"]},"delete":{"allowed":false,"scopes":[]}},"fields":[{"key":"name","name":"Company name","type":"text","required":true,"editable":true,"storage":"physical","storage_key":"name"},{"key":"industry","name":"Industry","type":"select","required":false,"editable":true,"storage":"physical","storage_key":"industry","options":[{"value":"Manufacturing","label":"Manufacturing"}]}],"relationships":[{"object":{"key":"contacts","name":"Contacts"},"cardinality":"one_to_many","labels":[]}],"workflow":{"id":"lifecycle-company","key":"company","name":"Company lifecycle"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}},"x-required-scopes":["records:read"],"x-preshos-annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true},"security":[{"ApiKey":[]}]}},"/workflows/{workflow_id}":{"get":{"operationId":"getWorkflow","tags":["Schema"],"summary":"Retrieve a status workflow","description":"Returns a workflow's statuses and the transitions allowed from each. Use the status ids with `POST …/records/{record_id}/status`.\n\n**Required scopes:** `records:read`","parameters":[{"name":"workflow_id","in":"path","required":true,"description":"Workflow id from an object definition.","schema":{"type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"The workflow.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Workflow"}},"required":["data"]},"example":{"data":{"id":"wf-deliverable","key":"deliverable","name":"Deliverable","statuses":[{"id":"st-draft","name":"Draft","transitions":[{"id":"st-in-review","name":"In review"}]},{"id":"st-in-review","name":"In review","transitions":[{"id":"st-approved","name":"Approved"}]}]}}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}},"x-required-scopes":["records:read"],"x-preshos-annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true},"security":[{"ApiKey":[]}]}},"/objects/{object_type}/records":{"get":{"operationId":"listRecords","tags":["Records"],"summary":"List records","description":"Lists records of one object type that the key's user may read. Results are scoped to the user's read grant: their own records, their teams' records, or the whole workspace. Use query parameters for simple filters; use `POST …/records/search` for richer queries.\n\n**Required scopes:** `records:read`","parameters":[{"name":"object_type","in":"path","required":true,"description":"Object type id from `GET /v1/objects`, e.g. `companies`, `work-items`, or a custom object id.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,99}$"}},{"name":"limit","in":"query","required":false,"description":"Page size (1–100).","schema":{"default":25,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"`next_cursor` from the previous page.","schema":{"type":"string","maxLength":500}},{"name":"q","in":"query","required":false,"description":"Case-insensitive match on the display field.","schema":{"type":"string","maxLength":200}},{"name":"fields","in":"query","required":false,"description":"Comma-separated field keys to include in each record's `fields` (max 20). Omit for identity fields only.","schema":{"type":"string","maxLength":2000}},{"name":"sort","in":"query","required":false,"description":"Comma-separated field keys; prefix `-` for descending. Max 3.","schema":{"type":"string","maxLength":200}},{"name":"filter","in":"query","required":false,"description":"`filter[field]=value` or `filter[field][op]=value` (eq, ne, lt, lte, gt, gte, in, is_null).","schema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}]}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"A page of records.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordList"},"example":{"data":[{"object_type":"companies","id":"48213","display":"Acme Corporation","status":"customer","owner_user_id":17,"created_at":"2026-09-02T14:11:08.000Z","updated_at":"2026-09-30T09:45:51.000Z","version":"9a1b2c3d4e5f60718293a4b5c6d7e8f9","fields":{"name":"Acme Corporation","domain":"acme.com","industry":"Manufacturing"}}],"pagination":{"limit":2,"has_more":true,"next_cursor":"eyJ2IjoxLCJvIjoyLCJxIjoiLi4uIn0"}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}},"x-required-scopes":["records:read"],"x-preshos-annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true},"security":[{"ApiKey":[]}]},"post":{"operationId":"createRecord","tags":["Records"],"summary":"Create a record","description":"Creates a record as the key's user. Field rules from the object definition apply: required fields, select options, validation, and field permissions. Status is set to the workflow's initial status. Owner defaults to the key's user. Work items require `fields.work_item_type_id`. Send an `Idempotency-Key` to retry safely.\n\n**Required scopes:** `records:write`","parameters":[{"name":"object_type","in":"path","required":true,"description":"Object type id from `GET /v1/objects`, e.g. `companies`, `work-items`, or a custom object id.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,99}$"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"201":{"description":"The created record.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordResponse"},"example":{"data":{"object_type":"companies","id":"48213","display":"Acme Corporation","status":"customer","owner_user_id":17,"created_at":"2026-09-02T14:11:08.000Z","updated_at":"2026-09-30T09:45:51.000Z","version":"9a1b2c3d4e5f60718293a4b5c6d7e8f9","fields":{"name":"Acme Corporation","domain":"acme.com","industry":"Manufacturing"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}},"x-required-scopes":["records:write"],"x-preshos-annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false},"security":[{"ApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fields":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Field values keyed by field key (see `GET /v1/objects/{object_type}`). Custom fields go under `custom_fields`."}},"required":["fields"],"additionalProperties":false},"example":{"fields":{"name":"Acme Corporation","domain":"acme.com","industry":"Manufacturing"}}}}}}},"/objects/{object_type}/records/search":{"post":{"operationId":"searchRecords","tags":["Records"],"summary":"Search records","description":"Structured search with operator filters, a text query, sorting, and field selection. Read-only: this POST never changes data and needs no Idempotency-Key.\n\n**Required scopes:** `records:read`","parameters":[{"name":"object_type","in":"path","required":true,"description":"Object type id from `GET /v1/objects`, e.g. `companies`, `work-items`, or a custom object id.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,99}$"}}],"responses":{"200":{"description":"A page of matching records.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordList"},"example":{"data":[{"object_type":"companies","id":"48213","display":"Acme Corporation","status":"customer","owner_user_id":17,"created_at":"2026-09-02T14:11:08.000Z","updated_at":"2026-09-30T09:45:51.000Z","version":"9a1b2c3d4e5f60718293a4b5c6d7e8f9","fields":{"name":"Acme Corporation","domain":"acme.com","industry":"Manufacturing"}}],"pagination":{"limit":50,"has_more":false,"next_cursor":null}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}},"x-required-scopes":["records:read"],"x-preshos-annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true},"security":[{"ApiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","maxLength":200,"description":"Case-insensitive match on the display field."},"filters":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},{"type":"null"},{"type":"object","properties":{"eq":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"ne":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"lt":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"lte":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"gt":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"gte":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"in":{"minItems":1,"maxItems":100,"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"is_null":{"type":"boolean"}},"additionalProperties":false}]},"description":"Map of field key → value or operator object. All filters are ANDed. A null value matches empty fields."},"fields":{"maxItems":20,"type":"array","items":{"type":"string"},"description":"Field keys to include in each record (max 20)."},"sort":{"maxItems":3,"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"direction":{"default":"asc","type":"string","enum":["asc","desc"]}},"required":["field"],"additionalProperties":false}},"limit":{"default":25,"type":"integer","minimum":1,"maximum":100},"cursor":{"type":"string","maxLength":500}},"additionalProperties":false},"example":{"filters":{"lifecycle_stage":{"in":["customer","opportunity"]},"created_at":{"gte":"2026-01-01T00:00:00Z"}},"fields":["name","domain","lifecycle_stage"],"sort":[{"field":"created_at","direction":"desc"}],"limit":50}}}}}},"/objects/{object_type}/records/aggregate":{"post":{"operationId":"aggregateRecords","tags":["Records"],"summary":"Aggregate records","description":"Groups the filtered records (up to 3 `group_by` fields) and computes 1–8 metrics (`count`, `count_distinct`, `sum`, `avg`, `min`, `max`) in the database over the complete filtered set. Omit `field` for `count(*)`.\n\n**Required scopes:** `records:read`","parameters":[{"name":"object_type","in":"path","required":true,"description":"Object type id from `GET /v1/objects`, e.g. `companies`, `work-items`, or a custom object id.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,99}$"}}],"responses":{"200":{"description":"Aggregated groups.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]},"example":{"data":[{"custom_status_id":"st_in_progress","total":42}],"pagination":{"limit":25,"has_more":false,"next_cursor":null}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}},"x-required-scopes":["records:read"],"x-preshos-annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true},"security":[{"ApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","maxLength":200},"filters":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},{"type":"null"},{"type":"object","properties":{"eq":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"ne":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"lt":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"lte":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"gt":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"gte":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"in":{"minItems":1,"maxItems":100,"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"is_null":{"type":"boolean"}},"additionalProperties":false}]},"description":"Map of field key → value or operator object. All filters are ANDed. A null value matches empty fields."},"group_by":{"maxItems":3,"type":"array","items":{"type":"string"}},"metrics":{"minItems":1,"maxItems":8,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$","description":"Result column name."},"op":{"type":"string","enum":["count","count_distinct","sum","avg","min","max"]},"field":{"type":"string"}},"required":["name","op"],"additionalProperties":false}},"order_by":{"type":"object","properties":{"name":{"type":"string"},"direction":{"type":"string","enum":["asc","desc"]}},"required":["name","direction"],"additionalProperties":false},"limit":{"default":25,"type":"integer","minimum":1,"maximum":100,"description":"Maximum groups per page."},"cursor":{"type":"string","maxLength":500}},"required":["metrics"],"additionalProperties":false},"example":{"filters":{"work_item_type_id":"deliverable"},"group_by":["custom_status_id"],"metrics":[{"name":"total","op":"count"}],"order_by":{"name":"total","direction":"desc"}}}}}}},"/objects/{object_type}/records/batch":{"post":{"operationId":"batchRecords","tags":["Records"],"summary":"Apply a batch of changes atomically","description":"Applies 1–100 operations to one object type in a single transaction: `create`, `update`, `status`, `delete`, `upsert` (match-and-update or create), `link`, and `unlink`. Every operation is authorized as the key's user before anything is written; if any operation fails, nothing is applied. Each existing record may appear once. `delete` operations also require the `records:delete` scope.\n\n**Required scopes:** `records:write`","parameters":[{"name":"object_type","in":"path","required":true,"description":"Object type id from `GET /v1/objects`, e.g. `companies`, `work-items`, or a custom object id.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,99}$"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Per-operation results; all operations succeeded.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","const":"completed"},"object_type":{"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"atomic":{"type":"boolean","const":true},"results":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"id":{"type":"string"},"status":{"type":"string","const":"succeeded"}},"required":["action","id","status"]}}},"required":["status","object_type","count","atomic","results"]}},"required":["data"]},"example":{"data":{"status":"completed","object_type":"companies","count":3,"atomic":true,"results":[{"action":"create","id":"48300","status":"succeeded"},{"action":"update","id":"48213","status":"succeeded"},{"action":"status","id":"48214","status":"succeeded"}]}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"412":{"$ref":"#/components/responses/Error412"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}},"x-required-scopes":["records:write"],"x-preshos-annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false},"security":[{"ApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"operations":{"minItems":1,"maxItems":100,"type":"array","items":{"oneOf":[{"type":"object","properties":{"action":{"type":"string","const":"create"},"fields":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Field values keyed by field key (see `GET /v1/objects/{object_type}`). Custom fields go under `custom_fields`."}},"required":["action","fields"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","const":"update"},"id":{"type":"string","minLength":1,"maxLength":200,"description":"Canonical record `id`."},"fields":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Field values keyed by field key (see `GET /v1/objects/{object_type}`). Custom fields go under `custom_fields`."}},"required":["action","id","fields"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","const":"status"},"id":{"type":"string","minLength":1,"maxLength":200,"description":"Canonical record `id`."},"status_id":{"type":"string","minLength":1,"maxLength":200}},"required":["action","id","status_id"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","const":"delete"},"id":{"type":"string","minLength":1,"maxLength":200,"description":"Canonical record `id`."}},"required":["action","id"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","const":"upsert"},"target":{"type":"string","minLength":1,"maxLength":100,"description":"Import target: the object type, or the work-item type slug for work items."},"match":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Match keys, e.g. `{ \"domain\": \"acme.com\" }`."},"fields":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["action","target","match"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","const":"link"},"id":{"type":"string","minLength":1,"maxLength":200,"description":"Canonical record `id`."},"association_id":{"type":"string","minLength":1},"target_id":{"type":"string","minLength":1,"maxLength":200,"description":"Canonical record `id`."}},"required":["action","id","association_id","target_id"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","const":"unlink"},"id":{"type":"string","minLength":1,"maxLength":200,"description":"Canonical record `id`."},"association_id":{"type":"string","minLength":1},"target_id":{"type":"string","minLength":1,"maxLength":200,"description":"Canonical record `id`."}},"required":["action","id","association_id","target_id"],"additionalProperties":false}]}}},"required":["operations"],"additionalProperties":false},"example":{"operations":[{"action":"upsert","target":"companies","match":{"domain":"acme.com"},"fields":{"name":"Acme Corporation"}},{"action":"update","id":"48213","fields":{"industry":"Aerospace"}},{"action":"status","id":"48214","status_id":"customer"}]}}}}}},"/objects/{object_type}/records/{record_id}":{"get":{"operationId":"getRecord","tags":["Records"],"summary":"Retrieve a record","description":"Returns one record with every field the key's user may read. The `ETag` header carries the record `version` for conditional updates. Records the user may not read return 404.\n\n**Required scopes:** `records:read`","parameters":[{"name":"object_type","in":"path","required":true,"description":"Object type id from `GET /v1/objects`, e.g. `companies`, `work-items`, or a custom object id.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,99}$"}},{"name":"record_id","in":"path","required":true,"description":"Canonical record `id`.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"fields","in":"query","required":false,"description":"Comma-separated field keys to return (max 20). Omit to return every field you may read.","schema":{"type":"string","maxLength":2000}}],"responses":{"200":{"description":"The record.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordResponse"},"example":{"data":{"object_type":"companies","id":"48213","display":"Acme Corporation","status":"customer","owner_user_id":17,"created_at":"2026-09-02T14:11:08.000Z","updated_at":"2026-09-30T09:45:51.000Z","version":"9a1b2c3d4e5f60718293a4b5c6d7e8f9","fields":{"name":"Acme Corporation","domain":"acme.com","industry":"Manufacturing"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}},"x-required-scopes":["records:read"],"x-preshos-annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true},"security":[{"ApiKey":[]}]},"patch":{"operationId":"updateRecord","tags":["Records"],"summary":"Update a record","description":"Partially updates a record: only the fields you send change. Unknown, read-only, or status fields reject the whole request (change status with the status endpoint). Send `If-Match: \"<version>\"` to fail with 412 if the record changed since you read it.\n\n**Required scopes:** `records:write`","parameters":[{"name":"object_type","in":"path","required":true,"description":"Object type id from `GET /v1/objects`, e.g. `companies`, `work-items`, or a custom object id.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,99}$"}},{"name":"record_id","in":"path","required":true,"description":"Canonical record `id`.","schema":{"type":"string","minLength":1,"maxLength":200}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"responses":{"200":{"description":"The updated record.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordResponse"},"example":{"data":{"object_type":"companies","id":"48213","display":"Acme Corporation","status":"customer","owner_user_id":17,"created_at":"2026-09-02T14:11:08.000Z","updated_at":"2026-09-30T09:45:51.000Z","version":"9a1b2c3d4e5f60718293a4b5c6d7e8f9","fields":{"name":"Acme Corporation","domain":"acme.com","industry":"Aerospace"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"412":{"$ref":"#/components/responses/Error412"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}},"x-required-scopes":["records:write"],"x-preshos-annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true},"security":[{"ApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fields":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Field values keyed by field key (see `GET /v1/objects/{object_type}`). Custom fields go under `custom_fields`."},"expected_version":{"type":"string","maxLength":200,"description":"Alternative to the If-Match header."}},"required":["fields"],"additionalProperties":false},"example":{"fields":{"industry":"Aerospace","custom_fields":{"tier":"enterprise"}}}}}}},"delete":{"operationId":"deleteRecord","tags":["Records"],"summary":"Delete a record","description":"Permanently deletes a record (CRM association rows are removed with it). Requires the `records:delete` scope, delete permission, and an object that allows deletion (`capabilities.delete`).\n\n**Required scopes:** `records:delete`","parameters":[{"name":"object_type","in":"path","required":true,"description":"Object type id from `GET /v1/objects`, e.g. `companies`, `work-items`, or a custom object id.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,99}$"}},{"name":"record_id","in":"path","required":true,"description":"Canonical record `id`.","schema":{"type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"Deletion confirmation.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"object_type":{"type":"string"},"deleted":{"type":"boolean","const":true}},"required":["id","object_type","deleted"]}},"required":["data"]},"example":{"data":{"id":"48213","object_type":"companies","deleted":true}}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}},"x-required-scopes":["records:delete"],"x-preshos-annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false},"security":[{"ApiKey":[]}]}},"/objects/{object_type}/records/{record_id}/status":{"post":{"operationId":"setRecordStatus","tags":["Records"],"summary":"Change a record's status","description":"Moves a record to another status of its workflow. The transition must be allowed by the workflow (see `GET /v1/workflows/{workflow_id}`); approval-gated statuses follow the same rules as the app.\n\n**Required scopes:** `records:write`","parameters":[{"name":"object_type","in":"path","required":true,"description":"Object type id from `GET /v1/objects`, e.g. `companies`, `work-items`, or a custom object id.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,99}$"}},{"name":"record_id","in":"path","required":true,"description":"Canonical record `id`.","schema":{"type":"string","minLength":1,"maxLength":200}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"The record after the transition.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordResponse"},"example":{"data":{"object_type":"companies","id":"48213","display":"Acme Corporation","status":"customer","owner_user_id":17,"created_at":"2026-09-02T14:11:08.000Z","updated_at":"2026-09-30T09:45:51.000Z","version":"9a1b2c3d4e5f60718293a4b5c6d7e8f9","fields":{"name":"Acme Corporation","domain":"acme.com","industry":"Manufacturing"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}},"x-required-scopes":["records:write"],"x-preshos-annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true},"security":[{"ApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status_id":{"type":"string","minLength":1,"maxLength":200,"description":"Target workflow status id."}},"required":["status_id"],"additionalProperties":false},"example":{"status_id":"customer"}}}}}},"/objects/{object_type}/records/{record_id}/relationships":{"get":{"operationId":"listRelationships","tags":["Relationships"],"summary":"Discover a record's relationships","description":"Lists the relationships registered for this record's object type, including which ones support link/unlink. Use an `id` from this list to read linked records.\n\n**Required scopes:** `records:read`","parameters":[{"name":"object_type","in":"path","required":true,"description":"Object type id from `GET /v1/objects`, e.g. `companies`, `work-items`, or a custom object id.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,99}$"}},{"name":"record_id","in":"path","required":true,"description":"Canonical record `id`.","schema":{"type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"Relationship definitions.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Association id."},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"object_type":{"type":"string","description":"Related object type."},"cardinality":{"type":"string","description":"`one_to_one`, `many_to_one`, `one_to_many`, or `many_to_many`."},"can_link":{"type":"boolean","description":"Whether link/unlink is supported through the API."},"source_field":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Reference field on this record, when the relationship is a field."}},"required":["id","label","object_type","cardinality","can_link","source_field"]}}},"required":["data"]},"example":{"data":[{"id":"214","label":"Contacts","object_type":"contacts","cardinality":"one_to_many","can_link":false,"source_field":null},{"id":"219","label":"Parent company","object_type":"companies","cardinality":"many_to_one","can_link":true,"source_field":"parent_company_id"}]}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}},"x-required-scopes":["records:read"],"x-preshos-annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true},"security":[{"ApiKey":[]}]}},"/objects/{object_type}/records/{record_id}/relationships/{association_id}":{"get":{"operationId":"listRelatedRecords","tags":["Relationships"],"summary":"List linked records","description":"Returns the records linked to this record through one relationship (field references, CRM associations, and custom links). Requires workspace-wide read on the related object type.\n\n**Required scopes:** `records:read`","parameters":[{"name":"object_type","in":"path","required":true,"description":"Object type id from `GET /v1/objects`, e.g. `companies`, `work-items`, or a custom object id.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,99}$"}},{"name":"record_id","in":"path","required":true,"description":"Canonical record `id`.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"association_id","in":"path","required":true,"description":"Relationship id from the discovery endpoint.","schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"limit","in":"query","required":false,"schema":{"default":25,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":500}}],"responses":{"200":{"description":"Linked records.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"object_type":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Record"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["object_type","data","pagination"]},"example":{"object_type":"contacts","data":[{"object_type":"contacts","id":"9001","display":"Ada Lovelace","status":null,"owner_user_id":17,"created_at":"2026-08-01T10:00:00.000Z","updated_at":"2026-09-01T10:00:00.000Z"}],"pagination":{"limit":25,"has_more":false,"next_cursor":null}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}},"x-required-scopes":["records:read"],"x-preshos-annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true},"security":[{"ApiKey":[]}]},"post":{"operationId":"linkRecord","tags":["Relationships"],"summary":"Link a record","description":"Links a target record through a relationship whose `can_link` is true. Reference relationships set the reference field (replacing the previous target); custom many-to-many relationships add a link. Requires update permission on this record and read permission on the target.\n\n**Required scopes:** `records:write`","parameters":[{"name":"object_type","in":"path","required":true,"description":"Object type id from `GET /v1/objects`, e.g. `companies`, `work-items`, or a custom object id.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,99}$"}},{"name":"record_id","in":"path","required":true,"description":"Canonical record `id`.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"association_id","in":"path","required":true,"description":"Relationship id from the discovery endpoint.","schema":{"type":"string","minLength":1,"maxLength":100}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Link result.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"association_id":{"type":"string"},"target_id":{"type":"string"},"linked":{"type":"boolean"}},"required":["id","association_id","target_id","linked"]}},"required":["data"]},"example":{"data":{"id":"48213","association_id":"219","target_id":"48001","linked":true}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"412":{"$ref":"#/components/responses/Error412"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}},"x-required-scopes":["records:write"],"x-preshos-annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true},"security":[{"ApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"target_id":{"type":"string","minLength":1,"maxLength":200,"description":"Id of the record to link."}},"required":["target_id"],"additionalProperties":false},"example":{"target_id":"48001"}}}}}},"/objects/{object_type}/records/{record_id}/relationships/{association_id}/{target_id}":{"delete":{"operationId":"unlinkRecord","tags":["Relationships"],"summary":"Unlink a record","description":"Removes a link created through a `can_link` relationship. A reference field is cleared only if it still points to `target_id` (otherwise 412).\n\n**Required scopes:** `records:write`","parameters":[{"name":"object_type","in":"path","required":true,"description":"Object type id from `GET /v1/objects`, e.g. `companies`, `work-items`, or a custom object id.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,99}$"}},{"name":"record_id","in":"path","required":true,"description":"Canonical record `id`.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"association_id","in":"path","required":true,"description":"Relationship id from the discovery endpoint.","schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"target_id","in":"path","required":true,"description":"Canonical record `id`.","schema":{"type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"Unlink result.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"association_id":{"type":"string"},"target_id":{"type":"string"},"linked":{"type":"boolean"}},"required":["id","association_id","target_id","linked"]}},"required":["data"]},"example":{"data":{"id":"48213","association_id":"219","target_id":"48001","linked":false}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"412":{"$ref":"#/components/responses/Error412"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}},"x-required-scopes":["records:write"],"x-preshos-annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true},"security":[{"ApiKey":[]}]}},"/objects/{object_type}/records/{record_id}/comments":{"get":{"operationId":"listComments","tags":["Comments"],"summary":"List a record's comments","description":"Returns the record's comment thread as plain text, newest first by default. Available for work items, companies, contacts, deals, meetings, and events.\n\n**Required scopes:** `comments:read`","parameters":[{"name":"object_type","in":"path","required":true,"description":"Object type id from `GET /v1/objects`, e.g. `companies`, `work-items`, or a custom object id.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,99}$"}},{"name":"record_id","in":"path","required":true,"description":"Canonical record `id`.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"`next_cursor` from the previous page.","schema":{"type":"string","maxLength":200}},{"name":"order","in":"query","required":false,"description":"`desc` = newest first.","schema":{"default":"desc","type":"string","enum":["desc","asc"]}}],"responses":{"200":{"description":"A page of comments.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Comment"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]},"example":{"data":[{"id":"c_8f2d","body":"Shared the revised proposal with the client.","author":{"kind":"user","id":17,"name":"Jordan Lee"},"created_at":"2026-09-30T15:02:11.000Z","updated_at":"2026-09-30T15:02:11.000Z"}],"pagination":{"limit":50,"has_more":false,"next_cursor":null}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}},"x-required-scopes":["comments:read"],"x-preshos-annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true},"security":[{"ApiKey":[]}]},"post":{"operationId":"createComment","tags":["Comments"],"summary":"Comment on a record","description":"Posts a comment as the key's user. Mentioned users (by user id) are notified when they can read the record. The comment appears in the app in real time, exactly like one written in the UI.\n\n**Required scopes:** `comments:write`","parameters":[{"name":"object_type","in":"path","required":true,"description":"Object type id from `GET /v1/objects`, e.g. `companies`, `work-items`, or a custom object id.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,99}$"}},{"name":"record_id","in":"path","required":true,"description":"Canonical record `id`.","schema":{"type":"string","minLength":1,"maxLength":200}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"201":{"description":"The created comment.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Comment"}},"required":["data"]},"example":{"data":{"id":"c_9a01","body":"@Jordan Lee Kickoff is confirmed for Monday.","author":{"kind":"user","id":23,"name":"Sam Rivera"},"created_at":"2026-10-01T12:00:00.000Z","updated_at":"2026-10-01T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}},"x-required-scopes":["comments:write"],"x-preshos-annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false},"security":[{"ApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":10000,"description":"Plain-text comment."},"mention_user_ids":{"maxItems":20,"type":"array","items":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"description":"Workspace user ids to @mention."}},"required":["body"],"additionalProperties":false},"example":{"body":"Kickoff is confirmed for Monday.","mention_user_ids":[17]}}}}}},"/search":{"get":{"operationId":"search","tags":["Search"],"summary":"Search across objects","description":"Full-text style search across work items, companies, contacts, meetings, events, and custom objects, filtered to what the key's user may read. Each hit carries `object_type` and `id` for the records endpoints.\n\n**Required scopes:** `records:read`","parameters":[{"name":"q","in":"query","required":true,"description":"Search text (2+ characters).","schema":{"type":"string","minLength":2,"maxLength":200}},{"name":"limit","in":"query","required":false,"schema":{"default":20,"type":"integer","minimum":1,"maximum":30}}],"responses":{"200":{"description":"Search hits, best first.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"}}},"required":["data"]},"example":{"data":[{"object_type":"companies","id":"48213","display":"Acme Corporation","subtitle":"acme.com","url":"/companies/48213"}]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}},"x-required-scopes":["records:read"],"x-preshos-annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true},"security":[{"ApiKey":[]}]}}},"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"preshos_v1_…","description":"Personal API key from Settings → Developer. Scopes: `records:read` (Read schema, records, relationships, workflows, and search.); `records:write` (Create and update records, change status, link/unlink, and batch edits.); `records:delete` (Delete records.); `comments:read` (Read record comments.); `comments:write` (Post record comments.); `users:read` (Read workspace members and teams.)."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key (1–255 visible ASCII characters, e.g. a UUID). Retrying with the same key and body replays the first successful response for 24 hours.","schema":{"type":"string","maxLength":255}},"IfMatch":{"name":"If-Match","in":"header","required":false,"description":"The record `version` (or its `ETag`). The update fails with 412 if the record changed.","schema":{"type":"string"}}},"headers":{"X-Request-Id":{"description":"Unique request id. Quote it when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the window resets.","schema":{"type":"integer"}}},"responses":{"Error400":{"description":"Invalid request: malformed JSON, failed validation, or an invalid filter/cursor.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error401":{"description":"Missing, invalid, revoked, or expired API key.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error403":{"description":"Insufficient key scope, developer access revoked, or missing object/record/field permission.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error404":{"description":"Object type, record, or route not found (or not readable by this user).","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error409":{"description":"Conflict, e.g. an Idempotency-Key request still in progress or a uniqueness violation.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error412":{"description":"If-Match / expected_version does not match the current record version.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error422":{"description":"The write was rejected by validation or workflow rules.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error429":{"description":"Rate limit exceeded. Retry after the Retry-After header.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error500":{"description":"Unexpected server error. Retry with backoff and quote the request_id.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error503":{"description":"A dependency is temporarily unavailable. Retry after a short delay.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"User":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"active":{"type":"boolean"},"teams":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name"]}}},"required":["id","name","email","title","active","teams"],"description":"A workspace member."},"Pagination":{"type":"object","properties":{"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Page size used for this response."},"has_more":{"type":"boolean","description":"Whether another page exists."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque cursor for the next page, or null."}},"required":["limit","has_more","next_cursor"],"description":"Cursor pagination. Pass `next_cursor` as `cursor` with the same query to fetch the next page."},"Team":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"member_ids":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},"required":["id","name","description","member_ids"],"description":"A team of workspace members."},"ObjectSummary":{"type":"object","properties":{"object_type":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"singular_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string","enum":["built_in","work_item","default"]},{"type":"string"}],"description":"`default` = tenant custom object."},"category":{"type":"string"},"display_field":{"anyOf":[{"type":"string"},{"type":"null"}]},"capabilities":{"$ref":"#/components/schemas/ObjectCapabilities"},"permissions":{"$ref":"#/components/schemas/ObjectPermissions"}},"required":["object_type","name","singular_name","description","kind","category","display_field","capabilities","permissions"],"description":"An object type available in this workspace."},"ObjectCapabilities":{"type":"object","properties":{"search":{"type":"boolean"},"create":{"type":"boolean"},"update":{"type":"boolean"},"delete":{"type":"boolean"}},"required":["search","create","update","delete"],"description":"Operations the object supports through the API, independent of the caller's permissions."},"ObjectPermissions":{"type":"object","properties":{"create":{"$ref":"#/components/schemas/PermissionAccess"},"read":{"$ref":"#/components/schemas/PermissionAccess"},"update":{"$ref":"#/components/schemas/PermissionAccess"},"delete":{"$ref":"#/components/schemas/PermissionAccess"}},"required":["create","read","update","delete"],"description":"What the calling user may do with this object type."},"PermissionAccess":{"type":"object","properties":{"allowed":{"type":"boolean"},"scopes":{"type":"array","items":{"type":"string","enum":["owned_by_user","owned_by_team","org_wide"]},"description":"Record scopes granted: your own records, your teams' records, or the whole workspace."}},"required":["allowed","scopes"],"description":"Advisory access for the calling user. Every request is still authorized individually."},"ObjectDefinition":{"type":"object","properties":{"object_type":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"singular_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"type":"string"},"category":{"type":"string"},"display_field":{"anyOf":[{"type":"string"},{"type":"null"}]},"capabilities":{"$ref":"#/components/schemas/ObjectCapabilities"},"permissions":{"$ref":"#/components/schemas/ObjectPermissions"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/Field"}},"relationships":{"type":"array","items":{"$ref":"#/components/schemas/RelationshipDefinition"}},"workflow":{"anyOf":[{"$ref":"#/components/schemas/WorkflowRef"},{"type":"null"}]},"work_item_types":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"workflow":{"anyOf":[{"$ref":"#/components/schemas/WorkflowRef"},{"type":"null"}]}},"required":["id","name","workflow"]},"description":"Work items only: active work-item types and their workflows."}},"required":["object_type","name","singular_name","description","kind","category","display_field","capabilities","permissions","fields","relationships","workflow"],"description":"Full description of an object type for this workspace and caller."},"Field":{"type":"object","properties":{"key":{"type":"string","description":"Key used in `fields` for reads, writes, filters, and sorting."},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"type":"string","description":"Data type, e.g. `text`, `number`, `date`, `select`, `boolean`, `reference`."},"required":{"type":"boolean"},"editable":{"type":"boolean"},"storage":{"type":"string","description":"`physical` columns are filterable/sortable; `jsonb` values live under `custom_fields`."},"storage_key":{"type":"string"},"options":{"type":"array","items":{"$ref":"#/components/schemas/FieldOption"}},"constraints":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["key","name","type","required","editable","storage","storage_key"],"description":"A field of an object type."},"FieldOption":{"type":"object","properties":{"value":{},"label":{"type":"string"}},"required":["value"],"additionalProperties":{},"description":"An allowed value for a select field."},"RelationshipDefinition":{"type":"object","properties":{"object":{"type":"object","properties":{"key":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["key","name"]},"cardinality":{"type":"string"},"labels":{"type":"array","items":{"type":"string"}}},"required":["object","cardinality","labels"],"description":"A relationship from this object to another."},"WorkflowRef":{"type":"object","properties":{"id":{"type":"string"},"key":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","key","name"],"description":"A status workflow reference. Fetch statuses with GET /v1/workflows/{workflow_id}."},"Workflow":{"type":"object","properties":{"id":{"type":"string"},"key":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"statuses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Status id. Send it to the status endpoint."},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"transitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name"]},"description":"Statuses this status may move to."}},"required":["id","name","transitions"]}}},"required":["id","key","name","statuses"],"description":"A status workflow with its statuses and allowed transitions."},"RecordList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Record"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"],"description":"A page of records."},"Record":{"type":"object","properties":{"object_type":{"type":"string","description":"Registry object type, e.g. `companies`, `work-items`, or a custom object id."},"id":{"type":"string","description":"Canonical record id. Use it for every record endpoint."},"public_id":{"type":"string","description":"Work items only: the legacy/public id used in app deep links."},"work_item_type_id":{"type":"string","description":"Work items only: the tenant work-item type (e.g. `task`)."},"display":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Primary display value (name/title)."},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Current status value or workflow status id."},"owner_user_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Owning user id, when the object has an owner."},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO-8601 UTC."},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO-8601 UTC."},"version":{"type":"string","description":"Opaque concurrency token. Send as `If-Match` on PATCH."},"fields":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["object_type","id","display","status","owner_user_id","created_at","updated_at"],"description":"A record of any object type. `fields` holds every readable business field keyed by field key; fields you may not read are omitted."},"RecordResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Record"}},"required":["data"],"description":"A single record."},"Comment":{"type":"object","properties":{"id":{"type":"string"},"body":{"type":"string","description":"Plain-text body."},"author":{"type":"object","properties":{"kind":{"anyOf":[{"type":"string","enum":["user","agent"]},{"type":"string"}]},"id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["kind","id","name"]},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","body","author","created_at","updated_at"],"description":"A comment on a record."},"SearchResult":{"type":"object","properties":{"object_type":{"type":"string"},"id":{"type":"string"},"display":{"anyOf":[{"type":"string"},{"type":"null"}]},"subtitle":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Deep link into the PRESHos app."}},"required":["object_type","id","display","subtitle","url"],"description":"A cross-object search hit."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found_error","conflict_error","idempotency_error","rate_limit_error","api_error"]},"code":{"type":"string","description":"Stable, machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation. May change; do not parse."},"param":{"type":"string","description":"The parameter or field that caused the error, when known."},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"request_id":{"type":"string","description":"Include this when contacting support."}},"required":["type","code","message","request_id"]}},"required":["error"],"description":"Every non-2xx response uses this envelope."}}},"x-error-codes":{"missing_api_key":{"status":401,"description":"No `Authorization: Bearer <key>` header was sent."},"invalid_api_key":{"status":401,"description":"The key is malformed, unknown, or does not verify."},"api_key_revoked":{"status":401,"description":"The key was revoked."},"api_key_expired":{"status":401,"description":"The key passed its expiry date."},"api_key_user_inactive":{"status":401,"description":"The key's user is deactivated."},"api_key_tenant_inactive":{"status":401,"description":"The workspace is suspended or not yet open."},"developer_access_revoked":{"status":403,"description":"The key's user no longer holds API Keys → create (developer access)."},"tenant_host_mismatch":{"status":403,"description":"The key belongs to a different workspace than the hostname."},"insufficient_scope":{"status":403,"description":"The key lacks the scope this endpoint requires."},"permission_denied":{"status":403,"description":"The key's user lacks the object, record, or field permission."},"object_not_available":{"status":404,"description":"Unknown object type, or the object is not exposed through the API."},"record_not_found":{"status":404,"description":"No record with this id that the caller can read."},"route_not_found":{"status":404,"description":"No endpoint matches this method and path."},"user_not_found":{"status":404,"description":"No workspace member with this id that you may read."},"workflow_not_found":{"status":404,"description":"No workflow with this id in the workspace."},"comments_not_supported":{"status":404,"description":"Records of this object type have no comment thread."},"search_not_supported":{"status":403,"description":"Listing and searching this object type is disabled for the workspace."},"conflict":{"status":409,"description":"Unique values already exist, a referenced record is missing or still referenced, or records changed concurrently."},"method_not_allowed":{"status":405,"description":"The path exists but not for this HTTP method."},"invalid_json":{"status":400,"description":"The request body is not valid JSON."},"validation_failed":{"status":400,"description":"Parameters or body failed validation; see `param` and `details`."},"invalid_filter":{"status":400,"description":"A filter, sort, or field selection is invalid."},"invalid_cursor":{"status":400,"description":"The pagination cursor is malformed or belongs to a different query."},"invalid_write":{"status":422,"description":"The write was rejected by field, owner, or workflow validation."},"write_not_supported":{"status":403,"description":"The object does not support this write through the API."},"stale_record":{"status":412,"description":"`If-Match` did not match the record's current version."},"idempotency_key_in_use":{"status":409,"description":"A request with this Idempotency-Key is still in progress."},"idempotency_key_reused":{"status":422,"description":"The Idempotency-Key was used with a different request."},"rate_limited":{"status":429,"description":"Too many requests for this key; retry after `Retry-After` seconds."},"payload_too_large":{"status":413,"description":"The request body exceeds 1 MB."},"unsupported_media_type":{"status":415,"description":"Send `Content-Type: application/json`."},"service_unavailable":{"status":503,"description":"A dependency (vault, database) is temporarily unavailable."},"internal_error":{"status":500,"description":"Unexpected server error. Retry with backoff and report the request_id."}}}