# AIssue account API

For coding agents and scripts that set up AIssue. Base URL: `https://aissue.yourgenlab.com/api/v1/`

**Authentication.** Send an account API token as a Bearer token. Users create tokens at https://aissue.yourgenlab.com/app/account/tokens; a token is shown once.

```
Authorization: Bearer aissue_pat_...
```

Treat the token as a password: never write it into files, commits or logs.

**Limits.** 120 requests per minute per user. Paths work with or without a trailing slash. Responses are JSON; errors look like `{"error": "..."}`.

The API cannot delete anything (except staff blog posts), manage tokens, or change billing. Those stay in the dashboard.

## Account

`GET /api/v1/me`: username, plan, and domain usage (`domains.can_create`).

## Domains (one per application)

`GET /api/v1/domains`: list. Each domain has `id`, `name`, `dsn`, `api_key`, `notification_emails`, `email_notifications`, `notification_cooldown_hours`, `dashboard_url`, `setup_url`.

`POST /api/v1/domains`: create.

```json
{"name": "my-shop", "notification_emails": ["dev@example.com"], "email_notifications": true}
```

Only `name` is required. Notification emails default to the account email. Errors:
- `409` if the name exists (the response includes the existing domain);
- `403` if the plan's domain limit is reached.

`GET /api/v1/domains/{id}` and `PATCH /api/v1/domains/{id}`: read or update `name`, `notification_emails`, `email_notifications`, `notification_cooldown_hours` (1–168).

`GET /api/v1/domains/{id}/setup?framework=django|nextjs|react|node|python|sentry|http`: setup instructions as Markdown, with the DSN filled in.

## Verification and issues

`GET /api/v1/domains/{id}/events?limit=10`: the latest events (max 50). Fields: `id`, `created_at`, `issue_id`, `title`, `exception_type`, `error_code`, `path`, `platform`, `sdk`, `release`, `environment`. No request data or user identity.

`GET /api/v1/domains/{id}/issues?status=open&limit=25`: issues. `status` is one of `open`, `unresolved`, `regressed`, `resolved`, `ignored`, `all`.

`POST /api/v1/issues/{id}/resolve`: mark an issue resolved, e.g. the setup test. Optional body `{"notes": "..."}`.

## GitHub

`GET /api/v1/domains/{id}/github`: whether a repository is connected, and the `connect_url` where the **user** connects one. Connecting requires the user to sign in to GitHub in a browser, so an agent cannot do it.

## Repositories: SBOM and AI-BOM

`GET /api/v1/repositories`: the repositories and projects added by hand (`id`, `full_name`, `source`, `domain`).

`GET /api/v1/repositories/{id}/bom?standard=cyclonedx&scope=full`: download the bill of materials, e.g. in CI. `standard` is `cyclonedx` (CycloneDX 1.7 JSON) or `spdx` (SPDX 2.3 JSON, SBOM only); `scope` (CycloneDX) is `full` (SBOM and AI-BOM), `sbom` or `aibom`. The SBOM lists the package versions from the lockfiles with purls, declared licenses and open vulnerabilities; the AI-BOM adds the AI models, datasets, prompts, AI services, MCP servers and vector databases, with the answers given about them.

## Sending errors

Errors are sent with the domain's DSN by the SDKs (see https://aissue.yourgenlab.com/install.md), not with the account token.

## MCP server

AIssue is also an MCP server (Model Context Protocol, Streamable HTTP) at `https://aissue.yourgenlab.com/mcp`, with the same token:

```
claude mcp add --transport http aissue https://aissue.yourgenlab.com/mcp --header "Authorization: Bearer aissue_pat_..."
```

Its tools go further than this API: projects, domains, issues and error events (with stack traces and AI analyses), running an AI analysis, vulnerable dependencies (overview, details with fix prompts, checking a lockfile, ignoring alerts, email settings), and the AI-BOM and SBOM (`get_ai_bom` lists the unanswered questions, `update_ai_bom` answers them, `export_bom` returns the documents). `tools/list` describes each tool and its arguments. Deleting a project is the only destructive tool; it keeps the project's domains.

The MCP server and this API work on every plan, including Free, with the account's normal plan limits: an AI analysis started here uses an AI credit like one started in the dashboard, and BOM exports (`export_bom`, the `/bom` download) need a paid plan. When a limit is reached, the error says which one and links to https://aissue.yourgenlab.com/app/billing. Plans: https://aissue.yourgenlab.com/#pricing.

## Blog (staff accounts)

Tokens of staff users can write blog posts, at `https://aissue.yourgenlab.com/api/v1/blog/` or with the MCP `blog_*` tools.

`POST /api/v1/blog/images`: upload an image, as multipart (`image`, `alt`, `title`) or JSON `{"filename": "chart.png", "data_base64": "...", "alt": "..."}`. PNG, JPEG, GIF or WebP, up to 8 MB. Returns its `id`, `url` and a `markdown` snippet.

`POST /api/v1/blog/posts`: create a post (a draft unless `"status": "published"`).

```json
{"title": "...", "summary": "...", "tags": ["security"], "cover_image_id": 3,
 "sections": [{"heading": "Why", "body": "Markdown text"},
              {"kind": "image", "image_id": 4, "caption": "..."},
              {"kind": "code", "language": "python", "body": "print(1)"}]}
```

`GET|PATCH|DELETE /api/v1/blog/posts/{id}`: read, change (only the fields sent; `sections` replaces them all; `"status": "published"` publishes) or delete. `GET /api/v1/blog/posts` and `GET /api/v1/blog/images` list them. Posts without `og_image_id` get a link preview image generated from the title. Drafts can be previewed at their `url` by staff signed in to the site.
