Due to increased demand, text TeamShift to hold the next available slot.+1 717 740 8200Call instead
TeamShift

Developers

TeamShift API

The TeamShift API lets your systems start work, review and decide approvals, manage automations, and give your team knowledge. Every request is scoped to the one workspace that owns the API key.

Base URL: https://api.teamshift.io. Requests and responses are JSON.

Authentication

Send a workspace API key as a bearer token on every request:

curl https://api.teamshift.io/v1/automations \
  -H "Authorization: Bearer ts_live_..."
  • Creating a key. A workspace owner or admin creates keys in the TeamShift portal under Settings → API keys. The full key, which starts with ts_live_, is shown once when it is created; afterwards the portal shows only its first characters.
  • Revoking a key. Click Revoke next to the key in the portal. A revoked key stops working immediately.
  • Rotating a key. Create a new key, switch your integration to it, then revoke the old one.
  • Keep keys server-side. A key acts for the whole workspace; never put it in a browser or mobile app.

Scopes

Each key carries one or more scopes, and each endpoint below lists the scopes it accepts.

  • programmatic:legacy: the general API scope, accepted by every endpoint on this page except /v1/connection. It is the default for keys created in the portal, where it is labelled “Trigger published automations”.
  • approvals:read and approvals:decide: read approvals, or decide them. These narrower scopes are granted to connected apps through TeamShift’s consent screen.

Errors

Errors use standard HTTP status codes with a JSON body of the form {"detail": "..."}.

  • 401: the key is missing, invalid, or revoked.
  • 403: the key’s scopes do not permit this endpoint.
  • 404: the resource does not exist in your workspace.
  • 409: the request conflicts with the current state, such as deciding an approval that was already decided differently.
  • 422: the request body or parameters are invalid.

Outcomes

Ask your team for an outcome and track the order it creates. idempotency_key is required (1 to 200 characters): repeating a key returns the original order with "idempotent": true and never starts a second run. callback_url is optional and is stored with the order, but TeamShift does not call it today, so poll the order’s status_url. Put plain-language instructions for your team in input.task. Email team@teamshift.io for the outcome slugs enabled for your workspace.

POST /v1/outcomes

Start an outcome. Returns 202 Accepted. Scope: programmatic:legacy.

{
  "outcome_slug": "your-outcome",
  "input": { "customer_name": "Acme Co" },
  "idempotency_key": "order-2026-10-03-001"
}
{
  "status": "accepted",
  "order_id": "…",
  "status_url": "/v1/orders/…",
  "workflow_id": "…",
  "workflow_run_id": "…",
  "idempotent": false
}

GET /v1/orders/{order_id}

Read an order and its fulfillment state. Scope: programmatic:legacy.

{
  "order": {
    "id": "…",
    "outcome_slug": "your-outcome",
    "fulfillment_state": "started",
    "workflow_run_id": "…",
    "created_at": "…",
    "updated_at": "…"
  }
}

Approvals

Anything that sends, pays, publishes, or deletes waits at an approval. These endpoints let your system review and decide them.

GET /v1/approvals?status=pending&limit=50

List approvals. status defaults to pending (use all for every state); limit is 1 to 200. Scope: approvals:read or programmatic:legacy.

{
  "approvals": [
    { "id": "…", "status": "pending", "title": "…", "created_at": "…", "review_packet": { "sufficient": true } }
  ]
}

GET /v1/approvals/{approval_id}

Read one approval and, once decided, its decision receipt. Scope: approvals:read or programmatic:legacy.

{ "approval": { "id": "…", "status": "approved" }, "receipt": { "decision": "approved" } }

POST /v1/approvals/{approval_id}

Decide an approval. decision is approve, request_changes, or reject; a note is required for request_changes. Sending the same decision again returns "status": "already_recorded"; a different decision on an already-decided approval returns 409. Scope: approvals:decide or programmatic:legacy.

{ "decision": "approve", "note": "Looks good." }
{
  "status": "recorded",
  "idempotent": false,
  "decision": "approved",
  "decision_recorded": true,
  "execution_resumed": true,
  "approval": { "id": "…", "status": "approved" },
  "run": { "id": "…" }
}

Automations

Automations are the recurring jobs your team runs for your workspace.

GET /v1/automations?limit=100&offset=0

List automations, paged by offset. limit is 1 to 200; next_offset is set when a full page came back. Scope: programmatic:legacy.

{
  "automations": [ { "id": "…", "name": "…", "status": "active", "version": 3 } ],
  "next_offset": null
}

GET /v1/automations/{automation_id}

Read one automation. Scope: programmatic:legacy.

{ "automation": { "id": "…", "name": "…", "status": "active" } }

POST /v1/automations/{automation_id}/pause

Pause an automation’s schedule. Reversible. Scope: programmatic:legacy.

{ "status": "paused" }

POST /v1/automations/{automation_id}/resume

Resume a paused automation’s schedule. Scope: programmatic:legacy.

{ "status": "active" }

Knowledge

Give your team reference material and search it. Uploads accept JSON (source_type text, file, or url) or a multipart/form-data request with one file field.

POST /v1/knowledge/documents

Add a document. Returns 201 Created. Scope: programmatic:legacy.

{ "name": "Service area", "source_type": "text", "content": "We serve Lancaster County." }
{ "document": { "id": "…", "name": "Service area" }, "embedded": true, "chunk_count": 1, "extraction": { } }

GET /v1/knowledge/documents?limit=100

List documents (limit 1 to 200). Scope: programmatic:legacy.

{ "documents": [ { "id": "…", "name": "Service area" } ] }

GET /v1/knowledge/documents/{document_id}

Read one document. Scope: programmatic:legacy.

{ "document": { "id": "…", "name": "Service area" } }

DELETE /v1/knowledge/documents/{document_id}

Delete a document. Scope: programmatic:legacy.

{ "status": "deleted" }

POST /v1/knowledge/search

Search documents. mode is hybrid (default), keyword, or vector; limit is 1 to 50 (default 10). Scope: programmatic:legacy.

{ "query": "Do you serve York?", "mode": "hybrid", "limit": 5 }
{
  "mode": "hybrid",
  "vector_available": true,
  "results": [ { "document": { "id": "…", "name": "Service area" }, "score": 0.03, "match_types": ["keyword", "vector"] } ]
}

Team catalog

Ready-made teams your workspace can add.

GET /v1/team-catalog

List catalog teams and whether your workspace already has each one. Scope: programmatic:legacy.

{
  "teams": [
    { "id": "…", "name": "…", "category": "…", "description": "…", "best_for": "…", "member_count": 3, "activated": false, "team_id": null }
  ]
}

POST /v1/team-catalog/{catalog_id}/activate

Add a catalog team to your workspace. Idempotent: calling it again returns the existing team with "created": false. Scope: programmatic:legacy.

{ "created": true, "team_id": "…", "name": "…", "status": "…" }

Metrics

GET /v1/metrics?lookback_days=90

Read your workspace’s source-traceable company metrics. lookback_days is 1 to 365 (default 90). Scope: programmatic:legacy.

{
  "metric_definitions": [ ],
  "series": [ ],
  "latest": { },
  "kpi_tree": { },
  "anomalies": [ ],
  "narrative": "…"
}

Connected apps

Connected apps are integrations registered with TeamShift that a workspace owner or admin approves on TeamShift’s consent screen. The approval issues the app a key limited to the scopes shown on that screen. A connected app can read or end its own connection:

GET /v1/connection

Read the connection behind the calling key. Scope: approvals:read, approvals:decide, inbox-classifications:read, or inbox-classifications:feedback.

{
  "connection": {
    "id": "…",
    "client_id": "…",
    "workspace_name": "…",
    "scopes": ["approvals:read"],
    "connected_at": "…",
    "webhook_configured": true
  }
}

DELETE /v1/connection

Disconnect. The app’s key stops working immediately. Scope: approvals:read, approvals:decide, inbox-classifications:read, or inbox-classifications:feedback.

{ "revoked": "…" }

Connected apps, and only connected apps, can receive change notifications at a webhook URL they register. A notification names what changed (approvals.changed, inbox_classifications.created, or connection.revoked) and carries no workspace data; the app then reads the change through the API. Each notification is signed in the X-TeamShift-Signature header as t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with the webhook secret>. To register a connected app, email team@teamshift.io.

MCP servers

TeamShift also speaks the Model Context Protocol, so assistant apps and agents can use your workspace as a set of tools.

  • Claude connector (OAuth): https://api.teamshift.io/v1/claude/mcp. Read-only. A workspace owner or admin signs in and approves one workspace; no API key is needed. Setup and tool list.
  • API-key server: https://api.teamshift.io/v1/mcp. Send Authorization: Bearer ts_live_... and JSON-RPC 2.0 requests (initialize, tools/list, tools/call, ping). The tools listed depend on the key’s scope.

Support

Read the privacy policy and terms. For API questions, key access, or connected-app registration, email team@teamshift.io.