Guide
MCP & AI tools
The PRESHos API is designed to be the foundation for Model Context Protocol (MCP) tools and AI agents. Every operation has a stable name and behavior hints, and the schema endpoints let a tool type its inputs for each workspace.
Each endpoint has a stable operationId (for example listRecords or createRecord) and MCP-style behavior hints. The OpenAPI document exposes them on every operation as x-preshos-annotations, alongside x-required-scopes:
"x-required-scopes": ["records:write"],
"x-preshos-annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": false
}| Hint | Meaning |
|---|---|
readOnlyHint | The operation never changes data. |
destructiveHint | The operation may remove data. Ask before calling it. |
idempotentHint | Repeating the call with the same input has no additional effect. |
| Operation | Endpoint | Read-only | Destructive | Idempotent |
|---|---|---|---|---|
getMe | GET /v1/me | yes | no | yes |
listUsers | GET /v1/users | yes | no | yes |
getUser | GET /v1/users/{user_id} | yes | no | yes |
listTeams | GET /v1/teams | yes | no | yes |
listObjects | GET /v1/objects | yes | no | yes |
getObject | GET /v1/objects/{object_type} | yes | no | yes |
getWorkflow | GET /v1/workflows/{workflow_id} | yes | no | yes |
listRecords | GET /v1/objects/{object_type}/records | yes | no | yes |
searchRecords | POST /v1/objects/{object_type}/records/search | yes | no | yes |
aggregateRecords | POST /v1/objects/{object_type}/records/aggregate | yes | no | yes |
batchRecords | POST /v1/objects/{object_type}/records/batch | no | yes | no |
createRecord | POST /v1/objects/{object_type}/records | no | no | no |
getRecord | GET /v1/objects/{object_type}/records/{record_id} | yes | no | yes |
updateRecord | PATCH /v1/objects/{object_type}/records/{record_id} | no | no | yes |
deleteRecord | DELETE /v1/objects/{object_type}/records/{record_id} | no | yes | no |
setRecordStatus | POST /v1/objects/{object_type}/records/{record_id}/status | no | no | yes |
listRelationships | GET /v1/objects/{object_type}/records/{record_id}/relationships | yes | no | yes |
listRelatedRecords | GET /v1/objects/{object_type}/records/{record_id}/relationships/{association_id} | yes | no | yes |
linkRecord | POST /v1/objects/{object_type}/records/{record_id}/relationships/{association_id} | no | no | yes |
unlinkRecord | DELETE /v1/objects/{object_type}/records/{record_id}/relationships/{association_id}/{target_id} | no | no | yes |
listComments | GET /v1/objects/{object_type}/records/{record_id}/comments | yes | no | yes |
createComment | POST /v1/objects/{object_type}/records/{record_id}/comments | no | no | no |
search | GET /v1/search | yes | no | yes |
Record payloads differ per workspace. A tool can call GET /v1/objects/{object_type} to get the field contract (keys, types, required, editable, options) and build a precise input schema for that workspace, including custom objects and custom fields. capabilities and permissions tell the tool which actions to offer the current user.
The full OpenAPI 3.1 document is public at /openapi.json and at https://api.preshos.com/v1/openapi.json. It includes JSON Schemas for every request and response, the error envelope, and x-error-codes. You can use it to generate clients or tool definitions.
A hosted PRESHos MCP server is planned. It will map these operations one-to-one to tools, authenticate with the same keys, and enforce the same scopes and user permissions, so anything you build on the API today carries over. No endpoint logic will live only in the MCP layer.