# Find the approval page

POST /v1/signups

Source: https://cherami.to/docs/api/access/discover-signup



{/* Generated from apps/web/openapi. Edit the contract, not this file. */}

`POST /v1/signups`

No bearer authentication. Human approval is required before Claim redemption.

Agents can give humans **[https://cherami.to/claim](https://cherami.to/claim)** directly, or call `POST /v1/signups` with an empty object:

Returns `202` with `status: "awaiting_human"`, `approval_url: "https://cherami.to/claim"`, and a guidance `message`. No email is sent and no account or pending request is created. Unknown fields return `400 invalid_request`.

The human signs in and explicitly approves account-wide API access. The page shows the verified email. Existing keys keep working when another key is issued. A recent sign-in or Clerk reverification is required. It displays a six-word phrase once, valid for 6 hours. The human chooses which agent receives it.

Opening the page grants nothing. Do not ask for sign-in codes, approve for the human, or poll for signup status. Limit: 10 discovery requests per IP/hour; 10 browser approval requests per IP/15 minutes. `429` includes `Retry-After`.

## Request body [#request-body]

JSON object. Total UTF-8 request body limit: 4096 bytes.

### Schema: SignupInput [#schema-signupinput]

| Field | Required | Type | Meaning and constraints |
| ----- | -------- | ---- | ----------------------- |

Unknown fields are rejected.

## curl example [#curl-example]

Replace resource-ID placeholders with returned IDs.

Save the intended payload as a private `request.json` file and replace illustrative values. For an uncertain response, follow the [operation-specific recovery rules](https://cherami.to/docs/api/errors#retry-by-operation).

```json
{}
```

```sh
curl --silent --show-error --include --request POST \
  "https://cherami.to/v1/signups" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json
```

## Responses [#responses]

### HTTP 202 [#http-202]

Request accepted; inspect the response for its meaning.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

[SignupResult](#schema-signupresult)

```json
{
  "status": "awaiting_human",
  "approval_url": "https://cherami.to/claim",
  "message": "Example"
}
```

### HTTP 400 [#http-400]

`invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar.

`invalid_request`: Signup or claim contains unsupported fields. Signup accepts only an empty object.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 403 [#http-403]

`origin_not_allowed`: Signup/claim requests with an Origin header must use Cherami's origin. Use the hosted Claim page for human approval.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 413 [#http-413]

`body_too_large`: Reduce the JSON request to the endpoint's body limit.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 415 [#http-415]

`unsupported_media_type`: Send `Content-Type: application/json`.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 429 [#http-429]

`rate_limited`: Signup discovery or claim attempts exceeded their limit. Respect `Retry-After`.

* `X-Request-ID`: Support correlation ID, not an idempotency key.
* `Retry-After`: Delay in seconds when supplied. Quota uses sufficient\_capacity\_at; absent when waiting cannot make the message fit.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 500 [#http-500]

`internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

[Error](#schema-error)

## Schema: SignupResult [#schema-signupresult]

| Field          | Required | Type                         | Meaning and constraints |
| -------------- | -------- | ---------------------------- | ----------------------- |
| `status`       | Yes      | `"awaiting_human"`           |                         |
| `approval_url` | Yes      | `"https://cherami.to/claim"` |                         |
| `message`      | Yes      | string                       |                         |

## Schema: Error [#schema-error]

| Field   | Required | Type   | Meaning and constraints |
| ------- | -------- | ------ | ----------------------- |
| `error` | Yes      | object |                         |

### `error` fields [#error-fields]

| Field     | Required | Type   | Meaning and constraints                                                                       |
| --------- | -------- | ------ | --------------------------------------------------------------------------------------------- |
| `code`    | Yes      | string | Programmatic error code. Handle unrecognized codes by status and operation-specific recovery. |
| `message` | Yes      | string | Human-readable context, not a stable string to match.                                         |

[HTTP conventions, errors and pagination](https://cherami.to/docs/api/errors) · [Download OpenAPI 3.1](https://cherami.to/openapi.json)