> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salesgraph.com/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

> Call the same commands over plain HTTP, without MCP.

The same engine behind the MCP tools is also available as a small REST API under `/api/v1`. Use
it from any HTTP client when you don't want to run an MCP connection. Every endpoint uses the
same [API key authentication](/authentication) and returns **markdown** (`Content-Type:
text/markdown`), except errors, which are JSON.

Base URL: `https://salesgraph.com`

## API inventory

All published REST endpoints below are standard Salesgraph service interfaces. No
customer-specific custom APIs are published here.

| Method | Path                         | Classification | Purpose                        |
| ------ | ---------------------------- | -------------- | ------------------------------ |
| `GET`  | `/api/v1/commands`           | Standard       | Returns the command catalog.   |
| `POST` | `/api/v1/commands/{command}` | Standard       | Runs a command.                |
| `GET`  | `/api/v1/runs/{kind}/{id}`   | Standard       | Polls an async run.            |
| `POST` | `/api/v1/audit`              | Standard       | Starts the org audit shortcut. |
| `GET`  | `/api/v1/audit?id=<id>`      | Standard       | Polls an org audit by id.      |

## List commands

```http theme={null}
GET /api/v1/commands
```

Returns the markdown command catalog (same content as the [`help`](/tools/help) tool).

```bash theme={null}
curl -s https://salesgraph.com/api/v1/commands \
  -H "Authorization: Bearer $SALESGRAPH_API_KEY"
```

## Run a command

```http theme={null}
POST /api/v1/commands/{command}
```

`{command}` is one of `research`, `competitors`, `gtm-audit`, `audit`, `help`. Send the
command's arguments as a JSON body. Optionally include `userContext` (string) for extra context.

```bash theme={null}
curl -s https://salesgraph.com/api/v1/commands/research \
  -H "Authorization: Bearer $SALESGRAPH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "topic": "Stripe" }'
```

* **Sync commands** (`research`, `competitors`, `help`) return `200` with the markdown result.
* **Async commands** (`gtm-audit`, `audit`) return `202` with the run id in the `X-Run-Id` or
  `X-Audit-Id` header and `X-Run-Status: running`. Poll the run endpoint below.

| Status | Meaning                                                |
| ------ | ------------------------------------------------------ |
| `200`  | Sync result returned as markdown.                      |
| `202`  | Async run started; poll for the result.                |
| `400`  | Invalid arguments.                                     |
| `401`  | Missing or invalid API key.                            |
| `404`  | Unknown command.                                       |
| `428`  | Onboarding required — finish your org's sales profile. |
| `429`  | Rate limited.                                          |

## Poll a run

```http theme={null}
GET /api/v1/runs/{kind}/{id}
```

`{kind}` is `gtm-audit` or `audit`; `{id}` is the run id from the start response. Returns a
status markdown line while running, and the full result markdown once `completed`. The
`X-Run-Status` header carries the current status.

```bash theme={null}
curl -s https://salesgraph.com/api/v1/runs/gtm-audit/<id> \
  -H "Authorization: Bearer $SALESGRAPH_API_KEY"
```

Returns `404` if the id is unknown or belongs to another organization.

## Org audit shortcut

```http theme={null}
POST /api/v1/audit
```

Starts your org's audit. By default returns `202` with a run id to poll. Pass `{"wait": true}`
(or `?wait=true`) to block until the audit finishes and return the result inline — note this can
take several minutes and returns `504` if it exceeds the server timeout (the run keeps going;
poll its id). `GET /api/v1/audit?id=<id>` polls an existing org audit.

```bash theme={null}
curl -s -X POST "https://salesgraph.com/api/v1/audit?wait=true" \
  -H "Authorization: Bearer $SALESGRAPH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

<Note>
  For agent integrations, prefer the [MCP server](/quickstart) — it handles tool discovery and
  invocation for you. The REST API is here for simple scripts and non-MCP clients.
</Note>