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

# Agents

> How coding agents and scripts read Apsio today, with the apsio CLI, skills, the read API and the MCP server, and what is coming for them.

Agents reach Apsio through the same public API as the console, with the same permissions:
directly, or through the MCP server.

## The apsio CLI

An agent with a shell, such as Claude Code, Codex or Cursor's terminal, can use the
[`apsio` CLI](/cli) (version 0.2.0 or later) with a project token in `APSIO_TOKEN`:

```sh theme={null}
apsio issues --kind crash --since 7d --jq '.issues[] | {id, type, users} | tojson' -r
apsio issue 3f9a0c2e7d1b4a6c8e0f1a2b3c4d5e6f
apsio sessions 7f3c9b02-5d1e-4a8b-9c0f-2e6a1d4be19a
apsio releases compare 4.12.0 4.13.0 --json
```

* `--json` prints the API's JSON, and `--jq` filters it inside the CLI, so the agent reads
  only the fields it needs. `-r` prints strings without quotes.
* Exit codes are stable (0 success, 1 network or server, 2 usage, 3 not authenticated, 4 bad
  input, 5 not found), and no command prompts when it is not attached to a terminal.
* `apsio issue open <id>` prints the console URL, so the agent can link a person to the
  evidence.

## Skills

The [`apsio-skills`](https://github.com/Apsio/apsio-skills) repository holds skills in the
Agent Skills format that teach an agent to use the CLI:

```sh theme={null}
npx skills add apsio/apsio-skills
```

| Skill | What it teaches |
| - | - |
| `apsio-triage-issue` | Triage a crash or error: the issue list, the symbolicated stack, the breadcrumbs, the session, missing symbols, then a proposed fix |
| `apsio-release-check` | Compare a new release with the one in production and decide go, no-go or wait |
| `apsio-upload-symbols` | Set up dSYM uploads from Xcode, CI or fastlane |

The skills are versioned with the CLI and name the CLI version they need.

## The read API

Without the CLI, call the [read API](/read-api) with a project token:

```sh theme={null}
curl -H "Authorization: Bearer $APSIO_TOKEN" \
  "https://api.apsio.io/v1/projects/$PROJECT_ID/issues?limit=10"
```

* The API is described by an OpenAPI 3.1 document at `https://api.apsio.io/v1/openapi.json`,
  which needs no token. Give it to the agent so it knows the endpoints and fields.
* These docs are published for agents too: `https://docs.apsio.io/llms.txt` lists every page,
  and `llms-full.txt` holds them all in one file.

## The MCP server

Apsio's MCP server is at `https://mcp.apsio.io/mcp` (Streamable HTTP). It is a client of the
read API: its tools return the same numbers as the console, with the same permissions. It is a
preview (v0).

**Sign in.** Add the URL to your MCP client (Claude Code, Claude Desktop, Cursor and others).
The client signs you in with your Apsio account through OAuth, in the browser, and then reads
every project of your organizations. Nothing is stored on the MCP server.

```sh theme={null}
claude mcp add --transport http apsio https://mcp.apsio.io/mcp
```

**Headless agents** (CI, bots) send a project token instead, which reads one project:

```sh theme={null}
claude mcp add --transport http apsio https://mcp.apsio.io/mcp \
  --header "Authorization: Bearer $APSIO_TOKEN"
```

**Clients without remote MCP** run the local bridge, which relays to the same server with the
token from `APSIO_TOKEN`:

```json theme={null}
{
  "mcpServers": {
    "apsio": {
      "command": "npx",
      "args": ["-y", "@apsio/mcp"],
      "env": { "APSIO_TOKEN": "apsio_pt_v0..." }
    }
  }
}
```

### Tools

All tools are read-only.

| Tool | What it answers |
| - | - |
| `list_projects` | Your projects and their apps. Start here |
| `get_release_health` | Crash-free sessions and users per release; with an app, the last 14 days day by day |
| `compare_releases` | Two releases side by side, adoption, and the issues new in the second |
| `list_issues` | Crashes, errors, ANRs, hangs and abnormal exits, by users, occurrences or recency |
| `get_issue` | One issue: the symbolicated stack (`file:line`), release, device and the breadcrumbs before it |
| `search_sessions` | Sessions by release, outcome, device, OS version, errors, issue, a network endpoint (failed requests only, if you like) or a slow screen |
| `get_session` | One session as a compact timeline |
| `query_vitals` | App start, screen load (TTID, TTFD), hang and ANR rates per release; with `metric`, app start by release, OS, device or prewarming, every screen with the hangs on it, or MetricKit's daily histograms |
| `compare_cohorts` | What a set of sessions (crashed, with an issue, behind a failing endpoint, on a slow screen) has more often than the rest |
| `list_endpoints` | The HTTP endpoints your apps call, by requests, error rate or latency |
| `get_endpoint` | One endpoint: statuses, releases, the slowest and latest failed requests with their trace ids and the link to your APM |
| `get_trace` | The device spans of one trace, and the same trace in your APM |

Every answer has a short summary and the data as JSON, a link to the console for each issue,
session and release, and stays within a size budget: long stacks and lists are cut, saying how
many items were left out, and lists page with `next_cursor`. The API writes every call the MCP
server makes to your organization's audit log, with the user or project token that made it and
the tool, before it reads anything. A sign-in token given to an MCP client works only through
the MCP server, not against the API directly.

Changing an issue's status, merging issues, sampling and the kill switch will come as write
tools behind an explicit permission. A SQL tool (`run_query`) is not available yet.

## Treat app text as data

Exception messages, log bodies, breadcrumbs, screen names and attributes are written by
your app and its users, so they can contain text that looks like instructions. When you pass
them to an agent, treat them as data, never as instructions. The CLI shows such text quoted
and escaped under a note that it is untrusted, and the skills tell the agent never to follow
it, run commands it mentions, or paste it into a shell. The MCP server puts this text only in
fields named `untrusted`, never in its own summaries, and says so in every answer.

## Coming soon

These are planned and not available yet:

| | What it is |
| - | - |
| CLI queries | A read-only query command in the CLI, once the API has an endpoint for it |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.