Skip to content

THE TELLENZE API

Your systems.
Shared context.

Bring useful information into your work. Connect your systems, read the context you need and record the next step with a clear history.

Read the API guideTry Tellenze
An illustrative flowing connection between systems
Systems sharing context · concept illustration

WHAT YOU CAN DO

Small connections. Useful outcomes.

The App API has versioned endpoints for selected work, documents and incoming Signals. Give your integration only the access it needs.

Base path /api/v1/appsUse the workspace API address shown in Account settings → Apps. Read and write permissions are separate.

Projects and workflow context

Find active projects your App can access. Read their workflow stages so new work starts in a valid stage that is not a completion stage.

  • GET /projects
  • GET /projects/{key-or-id}

projects:read

Work items

List and read tasks, create work with context and acceptance criteria, and update supported task details. You can change text, assignments, labels, complexity, dates and blocked state. Moving work between stages and marking it shipped stay in the workspace.

  • GET /work-items
  • GET /work-items/{identifier-or-id}
  • POST /work-items
  • PATCH /work-items/{identifier-or-id}

work-items:read · work-items:write

Focus groups

Read Focus groups in a project your App can access when Focus is enabled. New work can join a Planned or Active group using its ID and current version. Projects and Focus resources are read-only through the App API.

  • GET /focus-groups
  • GET /focus-groups/{id}

focus-groups:read

Documents and Knowledge

Read, create and update project documents in Markdown. Each saved change keeps a revision and records which App made it. Workspace Knowledge needs the separate Workspace documentation grant.

  • GET /documents
  • GET /documents/{id}
  • POST /documents
  • PATCH /documents/{id}

documents:read · documents:write

Signals intake and evidence

Submit a report, add evidence to an existing Signal and read shared Signals. Search by text, state, source or project. You need Starter or above and explicit Signals permissions. Members accept proposals and request processing.

  • POST /signals
  • GET /signals
  • GET /signals/{id}

signals:write · signals:read

Required Context before a write

Get the current guidance for the destination project, task or workspace. Read the returned revisions and include the receipt in the protected write. Missing access or changed guidance requires a fresh read.

  • POST /required-context

Permission for the write and for reading the required guidance

A USEFUL STARTING POINT

Three steps to get going.

01

Create an App

Go to Account settings → Apps. Administrators decide whether ordinary members can create new Apps.

02

Choose its access

Select projects and give separate read and write permissions. Copy the token once and keep it in your system’s secret store.

03

Make the connection

Use the API address shown in settings. Follow the page links in each response and record the result in your integration.

IN PRACTICE

A few useful connections to build.

These examples show possible workflows. Replace sample projects, identifiers and versions with your workspace values. Follow the current setup guide and, for MCP, the schema returned by tool discovery.

Every request uses your App credential.
Authorization: Bearer YOUR_APP_TOKEN
Accept: application/json
Content-Type: application/json

The paths below start after /api/v1/apps. Send writes as JSON with the Content-Type header. Work-item and document writes use an Idempotency-Key to avoid duplicate changes. Signals intake uses a stable client_submission_id. For a protected write, read the revisions returned by POST /required-context. Then include data.receipt as required_context_receipt in the write.

Create a work item

Bring an external report into work

Keep an external ticket connected to a clear outcome in the right project.

POST /work-items
Idempotency-Key: support-ticket-1842

{
  "project_key": "SUPPORT",
  "title": "Investigate failed checkout",
  "description": "Reported by the support integration.",
  "acceptance_criteria": "A customer can complete checkout."
}

Needs work-items:write. Keep the returned identifier and version. Retrieve Required Context first when it applies.

Read and update a work item

Read first. Then update the definition.

Record that a dependency is resolved while keeping another person’s newer changes.

GET /work-items?project_key=SUPPORT&per_page=25
GET /work-items/SUPPORT-42

PATCH /work-items/SUPPORT-42
Idempotency-Key: support-ticket-1842-update-1

{
  "version": 1,
  "description": "The provider supplied its logs.",
  "blocked": false
}

Needs work-items:read and work-items:write. Replace version 1 with the latest data.version. The description replaces the saved text. Setting blocked to false also clears the blocked reason.

Create a document

Save a useful process guide

Leave the agreed process beside the work so the next person can use it.

POST /documents
Idempotency-Key: support-runbook-create-1

{
  "project_key": "SUPPORT",
  "title": "Payment incident runbook",
  "body": "# Payment incidents\n\n1. Find the report.\n2. Check provider logs.\n3. Record the outcome."
}

Needs documents:write. Save data.id and data.version. To update it later, read the document first. Use PATCH with its ID, current version and the complete replacement body.

Submit evidence

Collect a Signal from a monitor

Collect a report for review. Submitting it does not automatically create work or mark work shipped.

POST /signals

{
  "client_submission_id": "accounts-monitor-event-42",
  "body": "Account login requests return HTTP 503.",
  "source_key": "accounts-monitor",
  "source_label": "Accounts monitor",
  "external_event_id": "event-42"
}

Needs signals:write on Starter or above. Keep client_submission_id stable on retries. Add signal_id to attach the evidence to an existing Signal.

Full setup guide

BUILD A CONNECTION THAT LASTS

Handle each response with care.

Follow the returned pages

Projects, work items, Focus groups and documents accept per_page from 1 to 100. Work, Focus and document lists accept project_key. Use links.next with the same headers to get the next page. Signals uses its own returned cursor and filters.

Read the latest state before retrying

If a response is lost, keep the exact request and its key. Work-item and document retries return the existing resource instead of creating duplicates. For a 409 conflict, read the latest state or context and review the change before retrying. Use a new key if you change the write.

Use the response as your guide

For 401, check your credentials. For 403, check permissions. For 422, check field errors. Follow Retry-After on 429. Keep App credentials on your server. Rotate or revoke them in App settings when access needs to change.

CLEAR PERMISSIONS

An App has a purpose. And a boundary.

Owner + permissions

An App can access only what both its saved permissions and its owner’s current membership and project access allow.

Safe retries

Supported writes use an Idempotency-Key to avoid repeating the same change. Updates need the current version. After a conflict, read the latest state before revising and retrying.

A clear scope

The App API does not manage members, project workflows or Required Context policies. It does not expose private repository paths or attachments.

A FEW USEFUL DETAILS

Know what to expect.

Is the API the same as MCP?

The API connects your own software using an App credential and selected permissions, called grants. MCP lets a compatible agent discover workspace tools under a member’s authorization.

Can the App API trigger email Powerups?

The current v1 App API covers the resources listed here and has no email-send endpoint. Use the reviewed task email workflow through supported web, Looper or deployed MCP tools.

Can my integration accept a Signals suggestion?

It can submit and read reports with the right permissions. Members accept suggestions, change workflow and request processing through supported web, MCP or confirmed Looper flows.

Where are the endpoint details?

The Apps guide is the main setup reference. It covers permissions, request examples, pagination, versions, Required Context and errors.

CHOOSE THE RIGHT CONNECTION

Different ways in. Shared work.

Connect through MCPHelp a compatible agent find your work, understand the context and use tools within its permissions. Keep decisions visible, wherever the conversation happens.Explore reviewed PowerupsUse your work’s context to prepare a useful next action. Draft the message or proposal, check the details and choose when to send or run it.

COME TAKE A LOOK

A little less busy.
A lot more together.

Curious? Join the waitlist and see how we welcome your team.

Tell us a little about your team. We’ll explain the next steps and invite you when we have capacity for your workspace.

Join waitlist Start with your email. No payment needed to join.