> For the complete documentation index, see [llms.txt](https://docs.shortcutco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shortcutco.com/developers/readme.md).

# Shortcut Developers

Build on Shortcut with the REST API, webhooks, and an MCP server for AI agents, all on one token and scope model.

Shortcut runs lawn care and field service businesses: customers and leads, estimates, recurring jobs, the daily schedule of visits, crews, and invoices. Read and change that data with the REST API, hear about changes with webhooks, and give AI agents the same access through the MCP server.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Quickstart</strong></td><td>A token, a read, and a new lead in your workspace in five minutes.</td><td><a href="/developers/quickstart.md">Quickstart</a></td></tr><tr><td><strong>API reference</strong></td><td>Every endpoint and object, with samples in curl, Node.js, and Python.</td><td><a href="/developers/api-reference/reference.md">API reference</a></td></tr><tr><td><strong>Webhooks</strong></td><td>Signed events when an invoice is paid, a visit is completed, or a lead comes in.</td><td><a href="/developers/webhooks/overview.md">Webhooks</a></td></tr><tr><td><strong>MCP server</strong></td><td>Connect Claude, ChatGPT, Cursor, or your own agent to a workspace.</td><td><a href="/developers/mcp/overview.md">MCP overview</a></td></tr></tbody></table>

## Your first request in 60 seconds

{% stepper %}
{% step %}

### Create a token

A company admin opens **Settings → API & integrations** in Shortcut and selects **Create token**. For a first look, choose **Custom** scopes with only **Read customers**, and a 30-day expiry. Shortcut shows the token once; copy it.
{% endstep %}

{% step %}

### Put it in your environment

```bash
export SHORTCUT_TOKEN="scut_live_paste_your_token_here"
```

{% endstep %}

{% step %}

### Call the API

`GET /v1/me` needs no scope. It confirms the token works and names its workspace.

{% tabs %}
{% tab title="curl" %}

```bash
curl https://api.shortcutco.com/v1/me \
  -H "Authorization: Bearer $SHORTCUT_TOKEN"
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
// first-request.mjs: Node.js 18 or later
const response = await fetch("https://api.shortcutco.com/v1/me", {
  headers: { Authorization: `Bearer ${process.env.SHORTCUT_TOKEN}` },
});
if (!response.ok) throw new Error(`Shortcut API ${response.status}: ${await response.text()}`);
const { data } = await response.json();
console.log(data.workspace.name);
```

{% endtab %}

{% tab title="Python" %}

```python
import os

import requests

response = requests.get(
    "https://api.shortcutco.com/v1/me",
    headers={"Authorization": f"Bearer {os.environ['SHORTCUT_TOKEN']}"},
)
response.raise_for_status()
print(response.json()["data"]["workspace"]["name"])
```

{% endtab %}
{% endtabs %}

```json
{
  "data": {
    "object": "token",
    "token": {
      "id": "7d1c2f0e-5b8a-4f2e-9c11-2a6b9f3e4d10",
      "name": "First look",
      "kind": "api_key",
      "scopes": ["customers:read"]
    },
    "workspace": {
      "id": "3f6a8e2b-1c4d-4e7f-8a9b-0c1d2e3f4a5b",
      "name": "Greenline Lawn Care",
      "timezone": "America/Denver",
      "today": "2026-10-16"
    },
    "rateLimit": { "limit": 600, "remaining": 599, "resetSeconds": 60 }
  }
}
```

{% endstep %}
{% endstepper %}

The [Quickstart](/developers/quickstart.md) goes on to create a lead and find it in the app.

## Authentication

Every request sends a workspace token in the `Authorization` header: `Authorization: Bearer scut_live_…`. A company admin creates tokens in **Settings → API & integrations** and chooses their scopes, such as `customers:read` or `leads:write`; a token can do exactly that and nothing more. Scopes that message customers, create invoices, or move money are separate and off by default. [Workspaces and tokens](/developers/concepts/workspaces-and-tokens.md) · [Scopes](/developers/concepts/scopes.md)

{% hint style="warning" %}
There is no separate test mode: a token reads and changes the real data of the workspace that created it. While you explore, use a short-lived token with read scopes only, and add write scopes when your integration needs them. Workspaces on Shortcut's dev environment use `scut_dev_` tokens and their own base URL; see [Environments](/developers/concepts/conventions.md#environments).
{% endhint %}

Keep tokens on your servers. The API sends no CORS headers, so a browser cannot call it directly.

## What you can build

* **Website and ad leads** that land in Shortcut the moment someone asks for a quote. [Push website leads](/developers/guides/push-website-leads.md)
* **Booking from another system**: create jobs from your service catalog, put them on the schedule, and pause, resume, or cancel them as plans change.
* **A morning briefing** that posts each crew's route to Slack before they roll out. [Daily schedule bot](/developers/guides/daily-schedule-bot.md)
* **A CRM or accounting export** that copies customers, visits, invoices, and payments into another system and keeps it current. [Sync](/developers/concepts/sync.md)
* **Instant reactions** when an invoice is paid, a visit is completed, or a lead comes in, without polling. [Webhooks](/developers/webhooks/overview.md)
* **An AI assistant** that answers "what's on the schedule today?" inside Claude or ChatGPT. [Connect Claude](/developers/mcp/connect-claude.md) or [Connect ChatGPT](/developers/mcp/connect-chatgpt.md)

## Versioning

The version is in the path: `https://api.shortcutco.com/v1`. Within `v1`, Shortcut only adds: new endpoints, new fields, new enum values, and new optional parameters, each listed in the [changelog](/developers/resources/changelog.md). Build your client to ignore fields and enum values it does not know. A change that would break a working client goes to a new version, and `v1` keeps working alongside it. Each webhook event names the API version its object is serialized in; see [Webhooks](/developers/webhooks/overview.md). Details in [Conventions](/developers/concepts/conventions.md#base-url-and-versions).

## Learn the conventions once

* [Glossary](/developers/concepts/glossary.md): every object and what it is in the app.
* [Conventions](/developers/concepts/conventions.md): requests, responses, pagination, dates, and money.
* [Sync](/developers/concepts/sync.md): `updatedSince`, `createdSince`, and the five-minute overlap.
* [Idempotency, retries, and rate limits](/developers/concepts/idempotency-and-retries.md).
* [Errors](/developers/concepts/errors.md): every code, its cause, and its fix.

The contract is machine-readable at `https://api.shortcutco.com/v1/openapi.json` (OpenAPI 3.1, no token needed): generate a typed client, import it into Postman, or give it to a coding assistant. [llms.txt](https://github.com/Shortcut-Lawn-Care/gitbook/tree/gitbook/developers/llms.txt) indexes these pages for AI tools.