Search the docs

Find a page, a section, or an endpoint.

Sign inGet started

Addresses

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

List addresses

get/api/v1/identities

Parameters

  • limitnumber
  • cursordate-time

Responses

  • 200A page of addresses.
  • 401No API key, or one that is not valid.
  • 404No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
  • 429Rate limited. `X-RateLimit-Reset` says when to retry.
bash
curl https://pidgeon.ai/api/v1/identities \
  -H "Authorization: Bearer $PIDGEON_API_KEY"

Generated · public/openapi.json

Create an address

post/api/v1/identities

Idempotent with an `Idempotency-Key` header: the same key returns the first result rather than creating a second address.

Body

  • domain_iduuidrequired
  • local_partstringrequired
  • display_namestring | null
  • typeenum

    human · team · application · workflow · agent

  • modeenum

    human · automated · hybrid

Responses

  • 201The address.
  • 401No API key, or one that is not valid.
  • 404No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
  • 429Rate limited. `X-RateLimit-Reset` says when to retry.
bash
curl https://pidgeon.ai/api/v1/identities \
  -X POST \
  -H "Authorization: Bearer $PIDGEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Generated · public/openapi.json

Fetch one address

get/api/v1/identities/{id}

Parameters

  • idstringrequired

Responses

  • 200The address.
  • 401No API key, or one that is not valid.
  • 404No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
  • 429Rate limited. `X-RateLimit-Reset` says when to retry.
bash
curl https://pidgeon.ai/api/v1/identities/{id} \
  -H "Authorization: Bearer $PIDGEON_API_KEY"

Generated · public/openapi.json

Update an address

patch/api/v1/identities/{id}

Parameters

  • idstringrequired

Body

  • display_namestring | null
  • modeenum

    human · automated · hybrid

  • capabilitiesobject
  • statusenum

    active · suspended · archived

Responses

  • 200The address.
  • 401No API key, or one that is not valid.
  • 404No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
  • 429Rate limited. `X-RateLimit-Reset` says when to retry.
bash
curl https://pidgeon.ai/api/v1/identities/{id} \
  -X PATCH \
  -H "Authorization: Bearer $PIDGEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Generated · public/openapi.json

Delete an address

delete/api/v1/identities/{id}

Takes its messages, routing rules and webhooks with it.

Parameters

  • idstringrequired

Responses

  • 204Deleted. No body.
  • 401No API key, or one that is not valid.
  • 404No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
  • 429Rate limited. `X-RateLimit-Reset` says when to retry.
bash
curl https://pidgeon.ai/api/v1/identities/{id} \
  -X DELETE \
  -H "Authorization: Bearer $PIDGEON_API_KEY"

Generated · public/openapi.json