# crob.at API guide for agents

Base URL: `https://crob.at`. Public team and reference operations are free. No API key or account is required. Send `Content-Type: application/json` for JSON bodies.

- [OpenAPI 3.1 contract](https://crob.at/openapi.json): routes, operation IDs, request and response schemas, examples, status codes, and authentication.
- [HTML guide](https://crob.at/api): endpoint reference and examples.
- [Onboarding](https://crob.at/.well-known/api-onboarding): access requirements and limits.

The OpenAPI file uses JSON Schema Draft 2020-12. Resolve local `$ref` pointers against the whole OpenAPI document. Schemas are under `components.schemas`. Do not treat the whole OpenAPI document as a request schema. Required fields and nullable types are explicit. Accept additional response fields.

## Choose an operation

| Task | Method and path | Data to read |
| --- | --- | --- |
| Read a saved paste | `GET /api/team/{slug}` | `teams[].paste` |
| Read one team in a collection | `GET /api/team/{slug}/{teamSlug}` | `paste` |
| Create a share link | `POST /api/team` | `url`, `image`, `slug` |
| Generate without saving | `GET /api/random-team/{format}` | `teamText`, `statsDate` |
| Save generated text | `POST /api/random-team/{format}/save` | `url`, `image`, `slug` |
| Find sample teams | `GET /api/samples/{tier}` | Metadata and slugs, not exports |
| Read Pokémon types | `GET /api/type-chart-data` | Array of `[name, [type, ...]]` pairs |
| Send product feedback | `POST /api/feedback` | `success` |

Paths use Showdown format IDs such as `gen9ou`. Generator support and data availability are narrower than Showdown format support. A random generated team is not the Showdown Random Battle format. For collection links, use the child slug in the shared URL. Do not assume a numeric index.

## Create and read a paste

This complete JavaScript example stores one Pokémon to demonstrate the API. It is not a complete battle team. Run it with Bun or another runtime that supports `fetch`.

```javascript
const base = 'https://crob.at';
const paste = [
  'Garchomp @ Choice Scarf',
  'Ability: Rough Skin',
  'EVs: 252 Atk / 4 SpD / 252 Spe',
  'Jolly Nature',
  '- Earthquake',
  '- Dragon Claw',
  '- Stone Edge',
  '- Iron Head'
].join('\n');

const response = await fetch(`${base}/api/team`, {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Example team',
    public: false,
    teams: [{format: 'gen9ou', paste}]
  })
});
if (!response.ok) throw new Error(await response.text());
const created = await response.json();
console.log(created.url); // Share this, not management_token.

const readResponse = await fetch(`${base}/api/team/${created.slug}`);
if (!readResponse.ok) throw new Error(await readResponse.text());
const saved = await readResponse.json();
console.log(saved.teams[0].paste);
```

Request schema: `CreateTeamRequest`. Response schemas: `CreatedTeam` and `Team`.

The `teams` array must contain at least one entry with non-empty `paste`. Optional fields include `name`, `author`, `description`, and `public`. Text must be a recognizable Showdown export, not a PokePaste URL. Use a JSON serializer so newlines decode correctly. Combined normalized team text must not exceed 500,000 characters. The server truncates names to 100 characters, author to 50, and description to 1,000 after trimming it.

Creation returns `201`. `public` defaults to `false`, which means unlisted. Anyone with the URL can read it. The private `management_token` appears only in the creation response. Keep it secret. It is not an API key. Share `url` and `image` only.

Successful storage does not prove battle legality or a complete team. `format_status` can be null. When present, inspect its `status`, `reasonCode`, and validator revision. An `unknown` result is not a proven invalid team. Check against your battle server's rules and version before play.

## Generate and save

```javascript
const response = await fetch('https://crob.at/api/random-team/gen9ou');
if (!response.ok) throw new Error(await response.text());
const generated = await response.json();
console.log(generated.teamText);

// Preserve this exact body and key for retries of this save.
const body = JSON.stringify({
  teamText: generated.teamText,
  idempotencyKey: crypto.randomUUID()
});
const savedResponse = await fetch('https://crob.at/api/random-team/gen9ou/save', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body
});
if (!savedResponse.ok) throw new Error(await savedResponse.text());
console.log((await savedResponse.json()).url);
```

Schemas: `GeneratedTeam`, `SaveGeneratedTeamRequest`, and `CreatedTeam`.

Generation does not store a team. Each request can produce different text. Keep `teamText` for a repeatable test. `statsDate` is the usage-data month, not a validator version. `cardsHtml` is presentation HTML; agents can use `teamText` directly.

Optional generator query parameters are `bias=staples|balanced|surprise`, `include`, and `exclude`. The default bias is `balanced`. Each Pokémon parameter accepts one name of at most 80 characters from the generator pool. URL-encode the name. The same Pokémon cannot be included and excluded.

A save returns `201`, or `200` for an existing identical save. Use a new random idempotency key for each new save. Keys accept 16–64 letters, digits, underscores, or hyphens. Reuse the same key, format, and text on retries. A key used for different input returns `409`. Generated saves are unlisted and do not return a management token.

## Sample teams

`GET /api/samples/gen9ou` returns an array of `SampleTeam` metadata. It can return `[]`. For each chosen result, retrieve `/api/team/{slug}` to get its Showdown text. Do not read `paste` from a sample-list entry.

## Errors, limits, and retries

Check HTTP status before reading success fields. JSON errors have an `error` string and can have `message` and `retryAfter`. For example:

```json
{"error":"Rate limit exceeded","retryAfter":60}
```

- `400`: fix input before another attempt.
- `404`: missing team or unavailable generator data.
- `409`: generated-save idempotency conflict. Keep one key and identical input for each logical save.
- `429`: wait for the `Retry-After` header, in seconds.
- `500` or `502`: reads can use bounded retries with increasing delays.

`POST /api/team` and `POST /api/feedback` are not idempotent. Do not automatically retry after an uncertain network result. For generated saves, retain the exact text and idempotency key. Do not generate another team as part of a save retry.

Per-client write limits are 500 team creations, 30 generated-team saves, and five feedback submissions per hour. Team write limits can include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`. Reset is an ISO 8601 timestamp. Limits are not a promise of unlimited read capacity.

## Browser session helpers

`GET /api/me` returns a current user or `{"user":null}`. `POST /api/showdown/assertion` requires a linked Showdown session. On success it returns an empty `303` redirect to Showdown, not JSON. It can return `400`, `401`, or `503`. These helpers serve crob.at browser flows. Team-data integrations do not need them. Never send a crob.at session cookie to another origin.

See [API terms](https://crob.at/api#terms), [security](https://crob.at/api#security), and [privacy](https://crob.at/privacy). Routes outside the published OpenAPI contract are UI implementation details.
