# Octomatica API developer quickstart

Embed an isolated Octomatica agent in your product. The API creates agent spaces, configures their instructions and tools, runs asynchronous turns, returns files, and reports usage per end user.

Human-readable developer page: https://octomatica.ru/developers

## Base URL and authentication

Base URL: `https://dash.octomatica.ru/v1`

Send `Authorization: Bearer octo_live_...` on every request. Create a key in the web dashboard under Integrations, API Keys. Prefer the scope that allows the key to control only spaces it creates.

See [auth.md](https://octomatica.ru/auth.md) for the credential workflow.

## Canonical flow

1. Create an isolated space with `POST /spaces` and save the returned `space_id`.
2. Store durable instructions with `PUT /spaces/{slug}/manifest`.
3. Configure built-in tools and optional external MCP servers with `PUT /spaces/{slug}/tools`.
4. Submit work with `POST /turns`. Send a unique `Idempotency-Key` header and a body containing `space`, `text`, and optionally `end_user_ref` and `metadata`.
5. Poll `GET /turns/{turn_id}` until the state is `done`, `failed`, or `cancelled`.
6. List and download artifacts through `/turns/{turn_id}/files` and `/files/{file_id}`.
7. Read usage with `GET /usage`, optionally grouped by `end_user`.

## Minimal example

```bash
curl -X POST https://dash.octomatica.ru/v1/spaces \
  -H "Authorization: Bearer $OCTOMATICA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"engine":"claude-code","title":"Customer research agent"}'
```

```bash
curl -X POST https://dash.octomatica.ru/v1/turns \
  -H "Authorization: Bearer $OCTOMATICA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6d54ad4e-0a99-4c90-9071-f24616ca89db" \
  -d '{"space":"SPACE_ID","end_user_ref":"customer-42","text":"Prepare a concise competitor brief with sources."}'
```

## Reliable integration rules

- Treat turns as asynchronous. Poll with capped backoff.
- Use one idempotency key per logical turn. Retrying without it can create a second paid turn.
- Treat `result` as a human-readable summary. For typed output, provide a tool with a typed input schema and ask the agent to deliver through it.
- Never put credentials in prompts. Store app credentials through the write-only `/spaces/{slug}/secret` endpoint.
- Allow only the built-in capability keys the space needs.
- Handle JSON errors by `error.code`, retain `trace_id`, and respect spending caps.

## References

- OpenAPI 3.1: https://octomatica.ru/openapi.json
- Interactive documentation: https://dash.octomatica.ru/v1/docs
- Live service schema: https://dash.octomatica.ru/api/openapi.json
- Full agent context: https://octomatica.ru/llms-full.txt
- Contact: labs@octomatica.ru