# ARTRA

> ARTRA (artra.ai) is an agentic outbound sales platform — email, SMS, LinkedIn, and dialer — used by individual sellers. AI agents can drive a seller's ARTRA account programmatically through a token-gated JSON API.

## For AI agents

ARTRA exposes an agent API at `/api/v1/agent`. Authenticate with a Personal Access Token (`Authorization: Bearer artra_pat_…`) that the seller mints at `/settings/api-tokens`. A token acts as that one seller and can never exceed their own permissions; per-token scopes narrow it further. Writes are dry-run by default — preview, then resend with `dry_run=false` to commit.

The easiest way to connect is the ARTRA MCP server (`mcp_server/`), which exposes these endpoints as MCP tools for Claude Desktop and other MCP clients.

- [OpenAPI spec](/api/v1/agent/openapi.json): machine-readable description of every endpoint, scope, and schema

## Endpoints

- `GET /api/v1/agent/whoami` — who the token acts as + its scopes (scope: any valid token)
- `GET /api/v1/agent/contacts?query=&limit=&offset=` — search/list the seller's contacts (scope: contacts:read)
- `GET /api/v1/agent/contacts/{id}` — one contact with address (scope: contacts:read)
- `GET /api/v1/agent/sequences` — list outreach sequences with contact counts (scope: sequences:read)
- `POST /api/v1/agent/sequences/{id}/contacts` — add contacts to a sequence, dry-run by default (scope: sequences:write)
- `POST /api/v1/agent/discover/parse` — parse a prospecting query, free (scope: discover)
- `POST /api/v1/agent/discover` — run prospect discovery, ~1 credit per company (scope: discover)
- `POST /api/v1/agent/enrich` — enrich contacts (find_email/find_phone), dry-run by default, costs credits (scope: enrich)
- `GET /api/v1/agent/workflows` — list AI outreach workflows (scope: outreach:run)
- `POST /api/v1/agent/workflows/{id}/start` — start an outreach workflow, dry-run by default (scope: outreach:run)
- `GET /api/v1/agent/executions/{id}` — poll an outreach execution's status (scope: outreach:run)

## Notes

- There is no raw "send email" endpoint by design: outbound only happens through sequences/workflows so ARTRA's deliverability limits and duplicate-send prevention always apply.
- Discovery is rate-limited and may be restricted to a seller's assigned accounts; responses include `filters_applied`, `filters_dropped`, and scope/credit metadata.