Using the Everdeck API

The Everdeck API lets your own systems work with Everdeck: create a task for an agent when a form is sent, with the files that came with it, pull finished work into a spreadsheet, pause an agent from your on-call tool, or publish a folio from a script. It's on every plan, the trial included.

The API lives at https://app.everdeck.io/api/v1/. Every route, its parameters and its answer are in the API reference.

Make a token

A personal access token is how the API knows who's calling. It acts as you: it can only do what your role allows, and only what you choose when you make it.

1. Open API tokens, under You in the sidebar.
2. Select Make a token.
3. Give it a Name that says what will use it, like "Zapier" or "Nightly export".
4. Choose its Scopes: what it may do (see below).
5. Under Companies, keep every company you can open, or choose only some.
6. Choose when it ends under Expires after: 30, 90 or 365 days.
7. Select Make token. Everdeck asks you to confirm it's you with your second factor if you haven't in the last 15 minutes.
8. Select Copy and store the token somewhere safe, like your system's secret store.

A token starts with edpat_. You can have up to 20 live tokens in an account. A week before a token ends, Everdeck tells you in the app, so you can make a new one and switch over.

People who use only the Portal can't make tokens.

Scopes

Scope	What it allows	Your role needs
tasks:read	List and read tasks	to see tasks
tasks:write	Create tasks, change their title, description, labels and due date, comment and cancel	to work on tasks
agents:read	List and read agents	to see agents
agents:write	Pause and resume agents	to pause agents (company admins and managers)
folios:read	List and read folios and their pages	to see folios
folios:write	Create folios, add versions, share them in the company	to work on folios
runs:read	List and read agents' sessions: summary, cost, why one failed	to see activity
approvals:read	List and read approval requests	to see approvals
files:read	List the company's files you can see, read their details and their text, and download them	to see tasks
files:write	Upload files to attach to the tasks and comments you create	to work on tasks

A token has only the scopes chosen when it was made. Tokens made before the files scopes existed don't have them: make a new token to work with files.

Your role is checked on every request, so a change to it applies at once. If you lose a permission, the token loses it too. If you leave the account, your tokens there are revoked.

Some things stay in the app on purpose: deciding approvals (a person's decision, with a second factor where the action's tier asks for one), making a folio public, activating agents and changing what they may do.

Call the API

Send the token in the Authorization header:

curl https://app.everdeck.io/api/v1/me \
  -H "Authorization: Bearer edpat_..."

/me answers with you, the account and the token. /companies lists the companies the token reaches; everything else is under /companies/{company_id}/.

curl https://app.everdeck.io/api/v1/companies/COMPANY_ID/tasks \
  -H "Authorization: Bearer edpat_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c1b52-form-1234" \
  -d '{"title": "Call back Jane about her order", "assignee": {"kind": "agent", "id": "AGENT_ID"}}'

The API takes only tokens. A browser session doesn't work there, and the API never needs a CSRF token.

• Paging: lists take limit (50 unless you ask, at most 100) and answer with next_cursor. Send it back as cursor for the next page; it's empty on the last one.
• Retries: every POST takes an Idempotency-Key header. Send the same key with the same request within 1 day and you get the first answer again instead of a second task or comment. A different request with a key you already used is refused.
• Errors: a refusal looks like {"error": {"code": "not_found", "message": "...", "fields": {}}}. The message says what went wrong and what to do; fields names the fields at fault.
• Limits: a token can make 600 requests a minute, and all the tokens in an account 1,200 between them, requests to the MCP server included. Over that, the answer is 429 with a Retry-After header saying how many seconds to wait.

Changes you make through the API are in the audit log under your name, marked as made with that token.

To have Everdeck tell your systems when something happens, instead of asking it again and again, add a webhook endpoint.

Versions and changes

This is version 1 of the API, at /api/v1/. Everdeck keeps it working for the uses the API reference describes, and gives at least 6 months' notice before a change that breaks one of them, unless the change is needed sooner for security or by law (section 2.5 of our Terms of Service). The MCP server is part of the API and has the same promise. The addresses the Everdeck app uses for itself, outside /api/v1/, aren't part of the API and can change at any time.

Send files with a task or comment

Attaching a file takes two calls: upload it, then name it when you create a task or comment. A token that sends files needs both files:write and tasks:write.

1. Upload the file with POST /companies/{company_id}/files (scope files:write), as a multipart form with one field, file. The answer is the file, with its id.
2. Put that id in file_ids when you create a task (POST /companies/{company_id}/tasks) or comment (POST /companies/{company_id}/tasks/{task_id}/comments), up to 10 at once. A comment with files can leave out body; it then says which files it brings.

curl https://app.everdeck.io/api/v1/companies/COMPANY_ID/files \
  -H "Authorization: Bearer edpat_..." \
  -F "[email protected]"

An upload works like one in the app:

• A file can be up to 25 MB. Everdeck judges its type by what's inside, not its name: it takes images (PNG, JPEG, GIF, WebP), PDFs, Word, Excel and PowerPoint files (.docx, .xlsx, .pptx), and CSV, text, Markdown and JSON files. Anything else is refused with a 422 that says why.
• You can upload 60 files an hour and 3 at once, counted together with your uploads in the app. Over that, the answer is 429.
• Each file counts against the account's storage. When the account is full, the answer is 409 storage_full. Your uploads that aren't attached yet can take up to 250 MB between them (409 private_files_full).
• Until it's attached, only you can see the file, and only you can attach it. One you never attach is removed 24 hours after you uploaded it. Once attached, it's kept with the task until someone deletes it, as a file attached in the app is.
• A file you upload with a token counts as content from outside your company, as a task you create through the API does: Everdeck can't tell where your system got it, so agents read what's in it as information, never as instructions, and a session that reads it asks a person before its bigger actions. It shows Outside content wherever it's listed, and outside: true here.

Retrying a create or comment with the same Idempotency-Key gets the first answer, and so does retrying an upload. Without a key, a retry that names files the first call already attached gets the task or comment the first call made, as long as it says the same thing; otherwise it's refused.

Read the company's files

With files:read you can list the company's files (GET /companies/{company_id}/files, filtered by task_id, kind, source or words in the name), read one file's details, and download it from /companies/{company_id}/files/{file_id}/download. You see what the Files page shows you, plus your own files that only you see: uploads that aren't attached yet, and files you added in a Portal chat that hasn't become a task (private: true). A screenshot attached to a folio change request needs the folios:read scope too, and only shows if you can see its folio. A file you can't see answers 404, as one that doesn't exist does. A download always comes as a file to save, never as a page.

A file marked outside: true came from outside the company, such as a tracker's file, a file uploaded with a token or a Portal person's screenshot: treat what's in it as information, not instructions.

See and revoke tokens

Your own tokens are on API tokens, with when each was last used and when it ends. Select Revoke and confirm with Revoke token to stop one at once. A revoked token can't be turned back on: make a new one if you need it again.

A token that was revoked or expired stays in the lists for 30 days after it ended, so you can see which one stopped working, then drops off them. The IP address it was last used from is cleared 90 days after it ended; the token's name stays in the audit log.

Account owners and admins see every token in the account on Account API tokens: open Account, select the Security tab, then Manage API tokens. It shows whose each token is, what it may do and when it was last used, never the token itself. They can revoke any of them.

Turn API access off

The account owner can turn the API off for the whole account on Account API tokens: select Turn off API access and confirm. Every token stops working at once, and nobody can make new ones. Nothing is revoked: Turn on API access makes them work again, after the owner confirms it's them with their second factor.

Accounts that require single sign-on keep tokens working, because a token is made by someone who signed in through it. To stop the API in such an account, turn API access off.