---
title: "Submit an agent (verified account session; Draft pending review)"
method: POST
path: "/api/submit"
---

# Submit an agent (verified account session; Draft pending review)

`POST /api/submit`

## Request

- Base URL: `https://theagentsindex.com`
- URL: `https://theagentsindex.com/api/submit`
- Auth: one of:
  - API key in cookie `__Secure-better-auth.session_token`
  - HTTP bearer

Requires an existing signed-in account with verified email. Sign in or create an account explicitly at https://theagentsindex.com/login?next=%2Fsubmit, verify its email, then send its session cookie. Identity and email come only from that session; submission never creates an account or sends verification email. Missing session returns 401 sign_in_required with an actionable loginUrl; unverified email returns 403 email_unverified with email and remediation. Neither refusal stores a listing or sends mail. Submissions come from the company itself: the account's address, or an address it proved with a code through /api/domain-proof/start and /api/domain-proof/verify, must be on the website's domain; otherwise the answer is 403 domain_unverified with the domain and remediation. A code to an address at the domain is the only proof. A research pass + quality gate decide publication; the Draft cannot inject page copy or self-publish. The fit check starts at once and usually answers within a minute: poll GET https://theagentsindex.com/api/submissions/{id} and wait the Retry-After seconds it sends while fit is "checking". fit then reads "accepted" (it goes live, and the account is mailed), "rejected" (mailed with the reason) or "undecided" (a person looks within 2 days). Authentication and verification precede idempotency: your own (url, session email) replay within 24h returns the existing draft (200). An Idempotency-Key header is accepted; the effective dedupe key is (url, session email).

## Headers

- `Idempotency-Key` string

## Request body

- SubmitInput: The website alone: we write its name and one-line description from its own pages.
  - `url` string, required: The website being submitted (https).

## Response `200`

Deduplicated — your existing draft for this (url, session email).

- SubmissionStatus
  - `id` string
  - `slug` string
  - `status` 'Draft' | 'Processing' | 'Review' | 'Published' | 'Rejected'
  - `submittedAt` string, date-time
  - `fit` 'checking' | 'accepted' | 'rejected' | 'undecided': Where the fit check stands. It runs right after submission and usually answers within a minute; undecided means a person decides it within 2 days.

## Other responses

- `201`: Draft created.
- `400`: Validation failed (bad url/name).
- `401`: Sign in or create an account explicitly at loginUrl, then verify email and retry. No account, mail or listing created.
- `403`: email_unverified: verify the session account email and retry. domain_unverified: prove an address at the returned domain with a code through /api/domain-proof/start and /verify, then retry. No listing or mail created.
- `409`: Already listed / duplicate, or free_limit: the account has its free listings (one a day, two in all).

---

[API](https://skmtc.dev/theagentsindex/apis/the-agents-index-machine-api.md) · [All operations](https://skmtc.dev/theagentsindex/apis/the-agents-index-machine-api/llms.txt) · [OpenAPI document](https://skmtc.dev/theagentsindex/apis/the-agents-index-machine-api/revisions/575bafbb80ad?raw)