{"openapi":"3.1.0","info":{"title":"Grist (BYOK) API","version":"0.1.0","description":"Grist (BYOK) lets an AI assistant read your own Grist data through the Grist API with a key you supply (API key). Read-only: 7 tools (get_profile, list_orgs, list_workspaces, get_document, list_tables, list_columns, list_records). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only ever sent to *.getgrist.com. Unofficial...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-grist.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-grist/docs"},"termsOfService":"https://connectorbay.com/byok-grist/terms"},"servers":[{"url":"https://byok-grist.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-grist/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_profile":{"post":{"operationId":"get_profile","summary":"Show the Grist user the key belongs to: id and name. Use for \"Which Grist account is my API key for\".","description":"Show the Grist user the key belongs to: id and name. Use for \"Which Grist account is my API key for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site":{"description":"Your Grist site: your team name (the part before .getgrist.com, for example 'acme'), or 'docs' for your personal site.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Site","type":"string"}},"required":["site"],"title":"get_profileArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_orgs":{"post":{"operationId":"list_orgs","summary":"List the Grist organizations (team sites and your personal area) you can access, with id, name, domain and your access l","description":"List the Grist organizations (team sites and your personal area) you can access, with id, name, domain and your access level. Use for \"Which Grist teams am I in\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site":{"description":"Your Grist site: your team name (the part before .getgrist.com, for example 'acme'), or 'docs' for your personal site.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Site","type":"string"}},"required":["site"],"title":"list_orgsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_workspaces":{"post":{"operationId":"list_workspaces","summary":"List the workspaces of an organization together with the documents in each (document id, name and access level). Use for","description":"List the workspaces of an organization together with the documents in each (document id, name and access level). Use for \"What Grist documents do I have in my team\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site":{"description":"Your Grist site: your team name (the part before .getgrist.com, for example 'acme'), or 'docs' for your personal site.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Site","type":"string"},"org_id":{"description":"Organization id from list_orgs, its subdomain such as 'acme', or 'current' for the site you are calling.","maxLength":200,"title":"Org Id","type":"string"}},"required":["site","org_id"],"title":"list_workspacesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_document":{"post":{"operationId":"get_document","summary":"Describe one document: name, access level, workspace and organization. Use for \"What is Grist document aKt9nEoy3UAJzw1p1","description":"Describe one document: name, access level, workspace and organization. Use for \"What is Grist document aKt9nEoy3UAJzw1p1CmxKq\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site":{"description":"Your Grist site: your team name (the part before .getgrist.com, for example 'acme'), or 'docs' for your personal site.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Site","type":"string"},"doc_id":{"description":"Document id (the string id from list_workspaces, 22 characters).","maxLength":200,"title":"Doc Id","type":"string"}},"required":["site","doc_id"],"title":"get_documentArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_tables":{"post":{"operationId":"list_tables","summary":"List the tables of a document (table ids). Use for \"What tables does my Grist document have\".","description":"List the tables of a document (table ids). Use for \"What tables does my Grist document have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site":{"description":"Your Grist site: your team name (the part before .getgrist.com, for example 'acme'), or 'docs' for your personal site.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Site","type":"string"},"doc_id":{"description":"Document id (the string id from list_workspaces, 22 characters).","maxLength":200,"title":"Doc Id","type":"string"}},"required":["site","doc_id"],"title":"list_tablesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_columns":{"post":{"operationId":"list_columns","summary":"List a table's columns with column id, label, type and whether it is a formula column. Use for \"What columns does my Gri","description":"List a table's columns with column id, label, type and whether it is a formula column. Use for \"What columns does my Grist table Contacts have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site":{"description":"Your Grist site: your team name (the part before .getgrist.com, for example 'acme'), or 'docs' for your personal site.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Site","type":"string"},"doc_id":{"description":"Document id (the string id from list_workspaces, 22 characters).","maxLength":200,"title":"Doc Id","type":"string"},"table_id":{"description":"Table id as shown in Raw Data (for example 'Contacts'), not the display name.","maxLength":200,"title":"Table Id","type":"string"},"hidden":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to include hidden columns such as manualSort.","title":"Hidden"}},"required":["site","doc_id","table_id"],"title":"list_columnsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_records":{"post":{"operationId":"list_records","summary":"List records of a table as id plus field values. Filter with a JSON object of allowed values per column, sort, and limit","description":"List records of a table as id plus field values. Filter with a JSON object of allowed values per column, sort, and limit the count. Use for \"Show the first 20 rows of my Grist table Contacts\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site":{"description":"Your Grist site: your team name (the part before .getgrist.com, for example 'acme'), or 'docs' for your personal site.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Site","type":"string"},"doc_id":{"description":"Document id (the string id from list_workspaces, 22 characters).","maxLength":200,"title":"Doc Id","type":"string"},"table_id":{"description":"Table id as shown in Raw Data (for example 'Contacts'), not the display name.","maxLength":200,"title":"Table Id","type":"string"},"filter":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"JSON object mapping column ids to arrays of allowed values, for example '{\"Status\": [\"Open\", \"Pending\"]}'.","title":"Filter"},"sort":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Column ids to sort by, comma-separated; prefix '-' for descending, for example 'Name,-Age'.","title":"Sort"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Maximum number of records to return (1 to 500).","title":"Limit"},"hidden":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to include hidden columns such as manualSort.","title":"Hidden"}},"required":["site","doc_id","table_id"],"title":"list_recordsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}