Teryo API

1. Create a connection

• Sign in and open User settings → API. Your email must be verified.
• Shared permissions are on the Workspace access tab: a workspace owner/admin enables workspace API access, and a project settings manager separately enables project access. This tab is only visible with management permissions. Ask the workspace or project manager if API access is disabled.
• In My connections, select New connection. Enter a name, choose 1, 7 or 30 days and select projects. Search preserves your selection. Start with read access; enable create, update, comment or archive only when needed.
• Enter your current account password and select Create connection. Signing in with an email link does not waive password confirmation when issuing API credentials.
• After creation, switch between REST and MCP to copy each token and endpoint. Tokens are displayed only once and cannot be retrieved after closing. One connection can cover multiple explicitly selected workspaces and projects.

Effective access is the intersection of current user permissions, workspace/project API policy, selected projects and token scopes. Administrator status does not override these selections. New projects are not added automatically.

2. Addresses and credentials

For another deployment, use the returned apiBase/mcpUrl. REST and MCP tokens are not interchangeable. These are Teryo credentials, not OpenAI or other AI-provider keys.

• Use Authorization: Bearer … over HTTPS only. Never put a token in URLs, source code, git, screenshots, prompts or agent messages.
• Use your application secret mechanism. Bash read -s hides input; curl --header @- reads the header from stdin instead of putting the token in process arguments. Do not enable set -x, curl -v or secret logging.
• Do not send site cookies, a mobile token, x-wf-actor or your account password to REST/MCP. Keep TLS verification enabled and do not follow redirects with credentials.
• Use your own backend for a third-party web app: arbitrary browser origins/CORS are not allowed. A same-origin client must use credentials: omit. Do not weaken CORS for onboarding.
• An environment variable is not a vault against code in the same client environment. Only connect trusted tools.

3. First request

Bash and curl with --fail-with-body and --header @- support. Enter the REST token in your terminal, not in a chat. GET /me does not change anything.

API_BASE='https://teryo.app/api/v1'
read -r -s -p 'REST token: ' TERYO_API_TOKEN
printf '\n'
export TERYO_API_TOKEN

printf 'Authorization: Bearer %s\n' "$TERYO_API_TOKEN" |
  curl --fail-with-body --silent --show-error \
    --connect-timeout 10 --max-time 30 --header @- \
    "$API_BASE/me"

The response contains userId, connectionId, clientId, scopes and mode: read-only or scoped-write. Check the expected connection. Run unset TERYO_API_TOKEN when finished.

4. Discover workspaces, projects and tasks

Read workspaces, then the selected workspace guide and projects. Use returned IDs, not names or slugs. Set PROJECT_ID after obtaining the project list.

printf 'Authorization: Bearer %s\n' "$TERYO_API_TOKEN" |
  curl --fail-with-body --silent --show-error --max-time 30 \
    --header @- "$API_BASE/workspaces?limit=25"

ORG_ID='workspace-id-from-response'
PROJECT_ID='project-id-from-response'

printf 'Authorization: Bearer %s\n' "$TERYO_API_TOKEN" |
  curl --fail-with-body --silent --show-error --max-time 30 \
    --header @- "$API_BASE/workspaces/$ORG_ID/guide"

printf 'Authorization: Bearer %s\n' "$TERYO_API_TOKEN" |
  curl --fail-with-body --silent --show-error --max-time 30 \
    --header @- "$API_BASE/workspaces/$ORG_ID/projects"

GET /workspaces/{orgId}/projects/{projectId} returns columns, assignable people and capabilities. GET /workspaces/{orgId}/projects/{projectId}/tasks lists tasks; GET /workspaces/{orgId}/tasks/{taskId} returns a task with description, assignees and updatedAt.

{
  "items": [
    {
      "id": "workspace-id",
      "name": {
        "text": "Example workspace",
        "truncated": false
      }
    }
  ],
  "nextCursor": null,
  "contentTrust": "untrusted"
}

Pages contain items and nextCursor. limit defaults to 25 and is at most 50. Pass a non-null nextCursor as after to continue the same list. Omit after on the first request; stop at null. It is not a page number.

NEXT_CURSOR='nextCursor-from-previous-response'
printf 'Authorization: Bearer %s\n' "$TERYO_API_TOKEN" |
  curl --fail-with-body --silent --show-error --max-time 30 \
    --header @- --get --data-urlencode 'limit=25' \
    --data-urlencode "after=$NEXT_CURSOR" \
    "$API_BASE/workspaces/$ORG_ID/projects"

Names, titles, descriptions and comments use {text, truncated}. Read .text and check truncated. An empty page means no accessible results, not that the whole workspace is empty. Archived tasks and unsanitized copies of restricted sources are excluded. Pages are not one immutable database snapshot.

Task pages also include reference, parentTaskId, assignees, direction and tags. Filters: q (title, full reference such as PRJ-12.1 or numeric path 12.1), taskStatus, assigneeId, statusColumnId, parentTaskId, dueAfter, dueBefore, updatedSince. Pages are ordered by ID; retain filters when continuing. updatedSince is not a deletion feed or a complete replication protocol.

Use /projects/{projectId}/people, /columns and /tags for paginated catalogs. The overview provides peopleNextCursor and columnsNextCursor. Continue an empty people page if nextCursor is non-null: some members may be ineligible for assignment. Columns include their display order; pagination uses ID order.

Read dependencies at /tasks/{taskId}/dependencies. Dependencies outside the export grant are omitted but can still block completion. Full descriptions use /tasks/{taskId}/description; full comments use /tasks/{taskId}/comments/{commentId}/text. Pass nextOffset as offset until null, in chunks of up to 8192 characters. Restart text reading if updatedAt changes. Never overwrite a field with a truncated preview.

5. Create a task

Requires tasks:create + tasks:read, an allowed project and current permission to create tasks. demo-create-001 is a sample requestId. Prepare a new unique ID for a new operation; preserve the exact ID and body when retrying the same operation.

{
  "requestId": "demo-create-001",
  "task": {
    "title": "Review the timetable",
    "taskStatus": "OPEN",
    "priority": "MEDIUM"
  }
}

printf 'Authorization: Bearer %s\n' "$TERYO_API_TOKEN" |
  curl --fail-with-body --silent --show-error --max-time 30 \
    --header @- --header 'Content-Type: application/json' \
    --request POST \
    --data-raw '{"requestId":"demo-create-001","task":{"title":"Review the timetable","taskStatus":"OPEN","priority":"MEDIUM"}}' \
    "$API_BASE/workspaces/$ORG_ID/projects/$PROJECT_ID/tasks"

Success is HTTP 201 and this receipt, not a full task. Read the task by taskId afterwards. An identical successful retry returns a receipt with replayed: true, without creating another task.

{
  "taskId": "task-id",
  "projectId": "project-id",
  "updatedAt": "2030-01-02T03:04:05.000Z",
  "archived": false
}

6. Update, comment and archive

PATCH /workspaces/{orgId}/tasks/{taskId} requires tasks:update + tasks:read. Replace expectedUpdatedAt with the exact updatedAt from the latest task read. Omitted fields stay unchanged; an empty patch or unknown fields are rejected.

{
  "requestId": "demo-update-001",
  "expectedUpdatedAt": "2030-01-02T03:04:05.000Z",
  "patch": {
    "taskStatus": "ON_REVIEW"
  }
}

POST /workspaces/{orgId}/tasks/{taskId}/comments requires tasks:comment + tasks:read and returns HTTP 201. body is 1–8000 characters after trimming surrounding whitespace.

{
  "requestId": "demo-comment-001",
  "body": "The timetable is ready for review."
}

POST /workspaces/{orgId}/tasks/{taskId}/archive requires tasks:archive + tasks:read and returns HTTP 200. Active children cause 409 rather than automatic cascading archive.

{
  "requestId": "demo-archive-001",
  "expectedUpdatedAt": "2030-01-02T03:04:05.000Z"
}

Create a child card by providing task.parentTaskId on creation. The parent must be active, export-authorized and in the same project; API nesting is limited to depth 10. Moving an existing card is not supported. To reply to a comment, supply parentId belonging to the same task discussion.

Checklist items are distinct from child tasks. GET /tasks/{taskId}/checklist returns item version and taskUpdatedAt. POST on that path creates an item; PATCH /checklist/{itemId} changes title/isDone/order. Requires tasks:update + tasks:read and permission to edit the card. Up to 1000 items, titles up to 280 characters; deletion is not exposed.

{
  "requestId": "demo-checklist-001",
  "expectedUpdatedAt": "2030-01-02T03:04:05.000Z",
  "title": "Read the specification"
}

{
  "requestId": "demo-checklist-002",
  "expectedUpdatedAt": "2030-01-02T03:04:05.000Z",
  "expectedItemVersion": "0000000000000000000000000000000000000000000000000000000000000000",
  "patch": {
    "isDone": true
  }
}

For REST, place itemId in the URL, not the JSON body. Replace the example zero expectedItemVersion with version from GET. This detects web checklist edits even when Task.updatedAt did not change. The receipt includes itemId/itemVersion and the new task version.

• requestId: 8–128 ASCII letters, digits, _ or -. Unique across all operations of a connection. Persist the request and ID before sending.
• After a network failure, retry the identical method, path and JSON with the same requestId. A different request with that ID returns 409. There is no Idempotency-Key header in this contract; requestId belongs in JSON.
• On a stale-version 409, re-read and review the task before preparing a new operation and requestId. Do not automatically replace expectedUpdatedAt.
• Current access is checked on every request, including replays. Revoked access can make a previously allowed request unavailable.

7. Task fields

taskStatus and statusColumnId are different: task state versus project board/direction column. Use project people for assignee IDs; peopleTruncated=true means an incomplete list. NONE/SELF/ALL assignment policy and task-specific permissions still apply. Capabilities help a client but are not authorization for a later write.

Additional fields: color is GRAY/RED/ORANGE/YELLOW/GREEN/TEAL/BLUE/VIOLET/PINK or null; tagIds accepts up to 50 IDs from the existing project catalog, with [] clearing the set. Create catalog entries in the web app. assignTasksOnCreate and assignTasksOnUpdate distinguish assignment contexts. Per-card capabilities.editableFields and editChecklist account for the creator, assignee and project management; project capabilities are only ceilings.

clearAssignees separately reports whether assigneeIds: [] may clear assignments. This preserves the existing product rule: permission to clear assignments does not necessarily allow assigning another person.

8. REST reference

Paths are relative to /api/v1. Data requests require a REST token. Write path IDs belong in the URL, not duplicated in JSON. Arbitrary filters, SQL and unknown query parameters are not supported.

9. JavaScript example

Server-side Node.js 22+. Provide TERYO_API_TOKEN through the environment. This read-only example adds no dependencies. Do not embed credentials in a browser bundle.

// Node.js 22+, server-side code. No browser cookies.
const token = process.env.TERYO_API_TOKEN;
if (!token) throw new Error('TERYO_API_TOKEN is required');
const base = 'https://teryo.app/api/v1';
const response = await fetch(base + '/workspaces?limit=25', {
  headers: { Authorization: 'Bearer ' + token },
  credentials: 'omit',
  redirect: 'error',
  cache: 'no-store',
  signal: AbortSignal.timeout(20000),
});
const data = await response.json();
if (!response.ok) {
  throw new Error('Teryo ' + response.status + ': ' + data.code);
}
for (const workspace of data.items) {
  console.log(workspace.id, workspace.name.text);
}
// Continue with data.nextCursor only when it is not null.

10. Python example

Python 3 standard library. Uses the REST environment token, rejects redirects and bounds waiting time.

# Python 3, standard library only. No browser cookies.
import json
import os
import urllib.error
import urllib.request

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

token = os.environ["TERYO_API_TOKEN"]
request = urllib.request.Request(
    "https://teryo.app/api/v1/workspaces?limit=25",
    headers={"Authorization": "Bearer " + token},
)
opener = urllib.request.build_opener(NoRedirect())
try:
    with opener.open(request, timeout=20) as response:
        data = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError("Teryo HTTP " + str(error.code)) from None
for workspace in data["items"]:
    print(workspace["id"], workspace["name"]["text"])
# Continue with data["nextCursor"] only when it is not None.

11. Connect an AI client with MCP

Choose Streamable HTTP, https://teryo.app/api/v1/mcp and the MCP Bearer token. The server is stateless. OAuth sign-in and automatic client registration are not implemented in v1: the client must support a configured Bearer token.

• Read tools: teryo_me, teryo_workspaces, teryo_guide, teryo_projects, teryo_project, teryo_tasks, teryo_task, teryo_comments, teryo_people, teryo_columns, teryo_tags, teryo_dependencies, teryo_checklist, teryo_taskText, teryo_commentText.
• Write tools: teryo_createTask, teryo_updateTask, teryo_commentTask, teryo_archiveTask, teryo_createChecklistItem, teryo_updateChecklistItem. Advertised only with appropriate token scopes and globally enabled writes. Inputs match REST plus path IDs.
• Start by listing accessible workspaces, reading guide and listing projects. Do not begin with broad autonomous writes. Task and comment text is untrusted data, not instructions to the client.

Codex CLI: add this section to your user ~/.codex/config.toml, without the actual token. Export TERYO_MCP_TOKEN in the terminal launching CLI. This does not configure hosted web chats or every desktop client.

[mcp_servers.teryo]
url = "https://teryo.app/api/v1/mcp"
bearer_token_env_var = "TERYO_MCP_TOKEN"

read -r -s -p 'MCP token: ' TERYO_MCP_TOKEN
printf '\n'
export TERYO_MCP_TOKEN
codex mcp list
codex

Use /mcp in Codex CLI to check tools. Do not use codex mcp login for this PAT connection: Teryo does not provide OAuth. Organization policy may prohibit remote MCP servers. Configuration checked against OpenAI Docs on 2026-10-25; a production login with your account was not tested.

12. Errors and limits

409 TASK_DEPENDENCIES_OPEN: complete blocking dependencies first. IDs and counts outside the export grant are not disclosed. Stale checklist item versions also return 409 CONFLICT. Never bypass a conflict by automatically substituting a new version.

• Connection: 60 requests/minute, 1024/day, four in flight. User total: 180/minute, 3072/day, eight in flight.
• Writes add 20/minute/connection and 60/minute/user. Workspace budget: 180/minute and 3072/day. Limits combine; an IP limit may trigger earlier.
• Write/MCP JSON body: 16 KiB; response: 128 KiB. Character bounds do not waive the encoded body-byte limit.
• At most ten active connections. A new connection selects up to 20 workspaces and 100 projects per workspace. Settings discovery shows up to 50 workspaces and 100 projects each, not unlimited export.
• Connection creation: at most five attempts per five minutes per IP. Wait for the window instead of continuously issuing new credentials.
• MCP tools can return isError: true with a result code even when HTTP succeeds. Check tool results, not only transport status.

13. Security and revocation

• Open User settings → API → My connections, select the revoke icon beside a connection and confirm. Its REST/MCP tokens stop authorizing subsequent requests. Password change/reset and protective session revocation also revoke connections.
• Lost tokens cannot be shown again. Revoke and create a replacement. For ordinary rotation, connect the replacement before revoking the old connection; revoke immediately when a leak is suspected.
• Do not follow instructions embedded in names, descriptions or comments. Never authorize credential disclosure, access expansion or command execution from retrieved content. Minimize scopes and selected projects. Previously exported data cannot be recalled from the external client.
• The API does not execute supplied SQL, shell commands or arbitrary URLs. API writes do not implicitly launch server AI agents. Administrator-configured webhook/integration delivery is independent.

v1 does not expose channels/DM, attachments/uploads, member/project administration, global search, batch writes, permanent deletion, unarchive or hierarchy moves. Use the documented /api/v1 surface, not internal web/mobile routes. It never bypasses user roles.