# 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 API key needed.

Give your human **[https://cherami.to/account](https://cherami.to/account)**. Calling this is optional: it returns the same `approval_url` and creates nothing.

On that page your human signs in, chooses **Get the message** under **Connect an agent**, and pastes you a message with a six-word phrase. The phrase works once, within 6 hours. [Redeem it](https://cherami.to/docs/api/access/redeem-claim) for an API key. There is no approval status to poll: wait for the message.

## Request body [#request-body]

JSON object, at most 4 KiB in total.

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

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

Unknown fields are rejected.

## curl example [#curl-example]

Save the payload as `request.json`.

```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]

Accepted.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[SignupResult](#schema-signupresult)

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

### HTTP 400 [#http-400]

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

`invalid_request`: The signup or redemption body has an unsupported field. Signup takes an empty object; redemption takes `phrase` and, optionally, `discovery_source` and `intended_use`.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 403 [#http-403]

`origin_not_allowed`: Signup and redemption refuse requests carrying another site's `Origin` header. Call them from the agent's runtime, not from a web page.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 413 [#http-413]

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

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 415 [#http-415]

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

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 429 [#http-429]

`rate_limited`: Too many signup or redemption requests from this network. Wait for `Retry-After`, then try again.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.
* `Retry-After`: Seconds to wait before retrying. For sending allowance it matches sufficient\_capacity\_at.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 500 [#http-500]

`internal_error`: The operation failed. Retry a read; after a write the change may have happened, so recover as [retry by operation](https://cherami.to/docs/api/errors#retry-by-operation) describes.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

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/account"` |                         |
| `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 | Code to handle. Handle a code you don't recognize by its HTTP status. |
| `message` | Yes      | string | Explanation of this case; its wording can change.                     |

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