Viably REST API

Every Viably tool, one HTTP call away.

Scripts, CI jobs and anything else that speaks HTTP can call the tools the MCP server gives agents, at /v1/<tool> with a personal access token. Reads take GET or POST, changes take POST, and every answer is the same JSON under data.

Create a token API reference

GET api.viably.app/v1/list_tasks

GET/v1/list_tasks?status=todo,blockedSend

curl https://api.viably.app/v1/list_tasks?status=todo,blocked \
  -H "Authorization: Bearer $VIABLY_TOKEN"

Response

One catalog

The tools your agent calls, as endpoints your scripts call.

The MCP server and the REST API serve one catalog, so a tool added to one appears in the other. The reference, the OpenAPI document and the grid below are all generated from it.

Open the full reference

Read from the live catalog at api.viably.app/v1/openapi.json

Authenticate

A token for each script, reaching only what it needs.

Create a personal access token on API and agents, tick what it may read and change, and send it as a bearer token. Viably keeps only a hash, so the token is shown once: put it straight into your CI's secrets.

viably.app/agents

Create a personal access token

Name

Nightly digest, GitHub Actions

Expires90 days

What it can read and change

Tasks

Deals

Your inbox

Create tasks, which post to Slack, and change their status, assignee and due date

Create token

Copy your token now

Viably keeps only a hash of it, so this is the one time it is shown.

Repository secrets

VIABLY_TOKENUpdated now

One token per script, so revoking one on API and agents leaves the others working.

Expires when you choose
30 days, 90 days, a year, or never. Each token shows when it last ran, which makes stale ones easy to spot.
Leaving ends it
Viably checks the member behind a token on every call. When someone leaves the workspace, their tokens stop working on the next request.
Revoke one, keep the rest
Give each script its own token. Revoking the one that leaked leaves the nightly job and the dashboard sync running.

A recipe

A nightly build that files its own failures.

One step at the end of a workflow turns a red build into an issue in #engineering, on the board, and on GitHub when the channel has a linked repository. The same shape works for a weekly digest built from list_deals, or a job that sweeps the inbox every morning.

.github/workflows/nightly.yml

name: nightly
on:
  schedule:
    - cron: "0 2 * * *"
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test
      - if: failure()
        run: |
          curl https://api.viably.app/v1/create_issue \
            -H "Authorization: Bearer ${{ secrets.VIABLY_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{"title": "Nightly tests failed on main", "channel": "engineering"}'

nightly

run 412

Check out
npm test
File the failure in Viably

#engineering

ViaApp2:04 AM

Issue created: Nightly tests failed on main

Reported by Nightly digest tokenTriage @oscar

Responses and limits

Plain statuses, and a budget you can see.

A failed call answers with a status and its reason under error. Each token gets 30 requests a minute on Free and 60 on Viably+, and a change costs 3. Every response carries an X-Request-Id to quote when you write to us about a call.

The tool ran. Its answer is under data.

{ "data": { "task": { "id": 3137, "channel": "ops" }, "note": null } }

One token, one minute

0of 30 used this minute

A read costs 1A change costs 3On Viably+

Every change on the record, refused ones included

API and agents lists each write with the member, the token or app that made it, the tool and the record it touched. A call Viably refused is listed with its reason, so a script reaching past its scopes shows up the first time it tries.

Agents use the same tools through the MCP server, and their changes land on the same list.

viably.app/agents

Changes, newest first

API and agents

create issue 221
Jim via Personal token
2 min ago
move deal 812
Jim via Personal token · refused: This token lacks the deals:write scope
9 min ago
create task 3137
Jim via Personal token
1 hour ago
claim contact 985
Jim via Claude Code
3 hours ago

FAQ

Questions about the API

How do I authenticate?

Create a personal access token on API and agents, pick what it may read and change, and send it in an Authorization: Bearer header. Every call acts as you, with your role.

How is the REST API different from the MCP server?

They serve the same catalog. The MCP server is for agents that sign in with OAuth and discover tools as they go; the REST API is for scripts and CI jobs that call a known endpoint with a token. A tool added to one appears in the other.

Is there an OpenAPI document?

Yes, at https://api.viably.app/v1/openapi.json. It is generated from the live catalog, as is the reference in the docs, so both list the same tools and fields.

What are the rate limits?

Each token gets 30 requests a minute on Free and 60 on Viably+, and a change costs 3. Tool calls also count against the workspace's monthly allowance, 500 on Free and 15,000 on Viably+. A refused call answers 429 with a Retry-After header.

Can a token do more than the person who made it?

No. A token carries its member's role and the scopes picked when it was made, and it stops working when that member leaves the workspace.

Does the API cost extra?

No. Every plan gets every endpoint, and each top-up pack adds 3,000 calls to the month.