Search the docs

Find a page, a section, or an endpoint.

Sign inGet started

Agent signup

Every agent signup endpoint, generated from the API's own schemas.

Sign an agent up

post/api/v1/agent/signup

The one call in this API that needs no key. An agent names a username and, optionally, the human who will own the mailbox; a six-digit code goes to that human and **nothing is created until it comes back**. Without a `human_email` the name is reserved and dormant — attach one with `POST /agent/human`.

Body

  • usernamestringrequired

    The local part you want on the shared domain.

  • human_emailemailrequired

    A person who can be reached. They receive the code that finishes the signup.

  • sourcestring | null

Responses

  • 201The pending signup.
  • 400The request is not valid. `error.field` names the input at fault when there is one.
  • 401No API key, or one that is not valid.
  • 402Your plan does not include this. `error.message` says what does.
  • 403Refused. `error.code` says why: `forbidden` when this key may not do this or the account is on hold, `abuse_blocked` when a limit says no.
  • 404No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
  • 409It conflicts with what is there: it already exists, or the `etag` you sent is not the current one.
  • 429Rate limited. `X-RateLimit-Reset` says when to retry.
  • 500Something went wrong on our side. Retry; if it keeps happening, tell us.
  • 503Something this needs is not answering right now. Retry in a moment.
bash
curl https://pidgeon.ai/api/v1/agent/signup \
  -X POST \
  -H "Authorization: Bearer $PIDGEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Generated · public/openapi.json

Name the human for a signup

post/api/v1/agent/human

For a signup that named none. Sends a fresh code and restarts the clock.

Body

  • signup_iduuidrequired

    From the signup this is finishing.

  • human_emailemailrequired

    A person who can be reached. They receive the code that finishes the signup.

Responses

  • 200The pending signup.
  • 400The request is not valid. `error.field` names the input at fault when there is one.
  • 401No API key, or one that is not valid.
  • 403Refused. `error.code` says why: `forbidden` when this key may not do this or the account is on hold, `abuse_blocked` when a limit says no.
  • 404No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
  • 409It conflicts with what is there: it already exists, or the `etag` you sent is not the current one.
  • 429Rate limited. `X-RateLimit-Reset` says when to retry.
  • 500Something went wrong on our side. Retry; if it keeps happening, tell us.
  • 503Something this needs is not answering right now. Retry in a moment.
bash
curl https://pidgeon.ai/api/v1/agent/human \
  -X POST \
  -H "Authorization: Bearer $PIDGEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Generated · public/openapi.json

Verify an agent with the human’s code

post/api/v1/agent/verify

Creates the account, the address and a workspace-scoped API key. Ten wrong codes spend the signup, whatever comes next. The key is returned once and never again — store it before doing anything else. It is minted here rather than at signup because this is the call a human has vouched for.

Body

  • signup_iduuidrequired

    From the signup this is finishing.

  • codestringrequired

Responses

  • 200The address.
  • 400The request is not valid. `error.field` names the input at fault when there is one.
  • 401No API key, or one that is not valid.
  • 402Your plan does not include this. `error.message` says what does.
  • 403Refused. `error.code` says why: `forbidden` when this key may not do this or the account is on hold, `abuse_blocked` when a limit says no.
  • 404No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
  • 409It conflicts with what is there: it already exists, or the `etag` you sent is not the current one.
  • 429Rate limited. `X-RateLimit-Reset` says when to retry.
  • 500Something went wrong on our side. Retry; if it keeps happening, tell us.
  • 503Something this needs is not answering right now. Retry in a moment.
bash
curl https://pidgeon.ai/api/v1/agent/verify \
  -X POST \
  -H "Authorization: Bearer $PIDGEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Generated · public/openapi.json