API overview
Conventions shared by every Outsend API endpoint — base URL, auth, content types, versioning, errors.
API overview
The Outsend API exposes the same surface that powers the web application. The dashboard and the API share one backend, one authentication scheme, and one set of objects.
Base URL
https://outsend.xyz
Endpoints under /api/ return JSON or stream events. The base URL is stable for the alpha.
Authentication
Sessions use a cookie named outsend_session. Obtain one by posting credentials:
POST /api/auth/login
Content-Type: application/json
{ "email": "name@example.com", "password": "..." }
The response sets outsend_session as HttpOnly, Secure, SameSite=Lax. Subsequent requests must include it. Sessions remain valid until logout (POST /api/auth/logout) or expiry. Requests without a valid cookie receive 401 on protected routes.
API tokens scoped per workspace are on the roadmap; cookie sessions are currently the only supported mechanism.
Content types
| Surface | Content type | Notes |
|---|---|---|
| Read and write endpoints | application/json |
UTF-8, snake_case fields |
| Event streams | text/event-stream |
Server-Sent Events |
| Downloads | application/octet-stream and friends |
Endpoints whose path ends in /download |
| Tabular exports | text/csv, application/json, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
Selected via ?format=csv|json|xlsx |
Endpoints that accept a format query parameter default to JSON when it is omitted.
Versioning
The API is in alpha. There is no /v1/ prefix and no version header — the surface evolves in place. Breaking changes are announced in advance through the changelog and, when relevant, through in-app banners. Additive changes ship without notice. A versioned prefix will be introduced before general availability.
Rate limits
Sensitive endpoints (authentication, contact, job creation) are protected by per-route quotas. Exceeded limits return 429 with a Retry-After header. See /docs/concepts/limits.
Errors
Failures return a JSON body and a conventional HTTP status:
{
"detail": "Human-readable message",
"errors": [
{ "field": "email", "message": "Invalid format" }
]
}
The errors array is present only when the failure is tied to specific input fields.
| Status | Meaning |
|---|---|
| 400 | Malformed request, business rule violation |
| 401 | No session, or session expired |
| 403 | Authenticated but not allowed; also returned for deactivated accounts |
| 404 | Resource does not exist, or is not visible to the caller |
| 422 | Request was well-formed but failed validation |
| 429 | Rate limit reached; retry after the header value |
| 5xx | Server-side fault; retries with backoff are safe |
Treat any 5xx as transient and apply exponential backoff.
Endpoint groups
| Group | Path | Purpose |
|---|---|---|
| Authentication | /docs/api/auth | Login, logout, signup, password reset, email verification |
| Jobs | /docs/api/jobs | Create, list, inspect, control, and export jobs |
| Pipelines | /docs/api/pipelines | Compose multi-step workflows and run them |
| Veille | /docs/api/veille | Continuous monitoring of queries and sources |
| Feedback | /docs/api/feedback | Submit in-product feedback and bug reports |
| Registry | /docs/api/registry | Discover available job types and their parameters |
SSE protocol
Long-running operations expose progress through Server-Sent Events. Event names, payload shape, and the state machine are documented at /docs/concepts/states-and-events.