Documentation menu
API reference

Account

Covers identity, onboarding, auth, entitlement, usage, billing and oauth. Every parameter, response and example below is generated from the contract.

The facts that belong to every operation rather than to this group, the refusal shape, the cursor rules, the filters and the credential each call accepts, are the other pages under API. What a field means is under Get started.

Operations
26
Tags
7
Need a credential
17
Public
9

identity

2 operations

Console sessions and the signed-in person.

POST/sessionPublic

Create Session

Sign in. The console holds the returned token and sends it as a bearer.

Operation ID create_session_session_post

Parameters

No parameters.

Responses

200
Session
Successful Response
422
HTTPValidationError
Validation Error

Example request

curl -X POST 'http://localhost:8000/session' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "person@example.com",
  "password": "<Password>",
  "organization_id": "string"
}'

Request body

SignInRequest

{
  "email": "person@example.com",
  "password": "<Password>",
  "organization_id": "string"
}

Example response

{
  "access_token": "<Access Token>",
  "expires_in": 1,
  "user_id": "<User Id>",
  "organization_id": "<Organization Id>",
  "email": "<Email>",
  "role": "<Role>",
  "token_type": "Bearer"
}
GET/meBearer token

Me

Who the current session belongs to.

Operation ID me_me_get

Parameters

No parameters.

Responses

200
Me
Successful Response

Example request

curl -X GET 'http://localhost:8000/me' \
  -H 'X-API-Key: $PLACESTACK_API_KEY'

Example response

{
  "user_id": "<User Id>",
  "organization_id": "<Organization Id>",
  "organization_name": "<Organization Name>",
  "email": "<Email>",
  "role": "<Role>",
  "organizations": [
    {
      "organization_id": "<Organization Id>",
      "name": "<Name>",
      "slug": "<Slug>",
      "role": "<Role>"
    }
  ]
}

onboarding

8 operations

Signing up, verifying, resetting a password, inviting and joining.

POST/organizationPublic

Create Organization

Create an organization and its first person, and sign them in.

Open registration is off in production until ALLOW_OPEN_SIGNUP says otherwise: invitations are the intended path in.

Operation ID create_organization_organization_post

Parameters

No parameters.

Responses

202
Response Create Organization Organization Post
Successful Response
422
HTTPValidationError
Validation Error

Example request

curl -X POST 'http://localhost:8000/organization' \
  -H 'Content-Type: application/json' \
  -d '{
  "organization_name": "<Organization Name>",
  "email": "person@example.com",
  "password": "<Password>",
  "first_name": "string",
  "last_name": "string"
}'

Request body

SignUpRequest

{
  "organization_name": "<Organization Name>",
  "email": "person@example.com",
  "password": "<Password>",
  "first_name": "string",
  "last_name": "string"
}

Example response

{
  "key": "string"
}
POST/verificationPublic

Create Verification

Redeem an emailed verification link. Until this happens, sign-in refuses.

Operation ID create_verification_verification_post

Parameters

No parameters.

Responses

200
Response Create Verification Verification Post
Successful Response
422
HTTPValidationError
Validation Error

Example request

curl -X POST 'http://localhost:8000/verification' \
  -H 'Content-Type: application/json' \
  -d '{
  "token": "<Token>"
}'

Request body

VerificationRequest

{
  "token": "<Token>"
}

Example response

{
  "key": "string"
}
POST/password-resetPublic

Create Password Reset

Ask for a reset link. Says the same thing whether or not the account exists.

Operation ID create_password_reset_password_reset_post

Parameters

No parameters.

Responses

200
Response Create Password Reset Password Reset Post
Successful Response
422
HTTPValidationError
Validation Error

Example request

curl -X POST 'http://localhost:8000/password-reset' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "person@example.com"
}'

Request body

PasswordResetRequest

{
  "email": "person@example.com"
}

Example response

{
  "key": "string"
}
PUT/passwordPublic

Set Password

Set a new password with a reset token.

Operation ID set_password_password_put

Parameters

No parameters.

Responses

200
Response Set Password Password Put
Successful Response
422
HTTPValidationError
Validation Error

Example request

curl -X PUT 'http://localhost:8000/password' \
  -H 'Content-Type: application/json' \
  -d '{
  "token": "<Token>",
  "password": "<Password>"
}'

Request body

PasswordUpdate

{
  "token": "<Token>",
  "password": "<Password>"
}

Example response

{
  "key": "string"
}
GET/invitationBearer token

List Invitations

Outstanding and past invitations for the caller's organization, newest first.

Operation ID list_invitations_invitation_get

Parameters

No parameters.

Responses

200
Response List Invitations Invitation Get
Successful Response

Example request

curl -X GET 'http://localhost:8000/invitation' \
  -H 'X-API-Key: $PLACESTACK_API_KEY'

Example response

[
  {
    "id": "<Id>",
    "email": "<Email>",
    "role": "<Role>",
    "status": "<Status>",
    "expires_at": "2026-09-13T12:00:00Z",
    "created_at": "2026-09-13T12:00:00Z"
  }
]
POST/invitationBearer token

Create Invitation

Invite someone into the caller's organization.

Operation ID create_invitation_invitation_post

Parameters

No parameters.

Responses

201
Invitation
Successful Response
422
HTTPValidationError
Validation Error

Example request

curl -X POST 'http://localhost:8000/invitation' \
  -H 'X-API-Key: $PLACESTACK_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "person@example.com",
  "role": "member"
}'

Request body

InvitationRequest

{
  "email": "person@example.com",
  "role": "member"
}

Example response

{
  "id": "<Id>",
  "email": "<Email>",
  "role": "<Role>",
  "status": "<Status>",
  "expires_at": "2026-09-13T12:00:00Z",
  "created_at": "2026-09-13T12:00:00Z"
}
DELETE/invitation/{invitation_id}Bearer token

Revoke Invitation

Revoke a pending invitation. The emailed link stops working immediately.

Operation ID revoke_invitation_invitation__invitation_id__delete

Parameters

path

invitation_idrequiredstring
No description.

Responses

204
empty
Successful Response
422
HTTPValidationError
Validation Error

Example request

curl -X DELETE 'http://localhost:8000/invitation/invitation_id_123' \
  -H 'X-API-Key: $PLACESTACK_API_KEY'
POST/membershipPublic

Create Membership

Redeem an invitation and join the organization, signed in.

No verification email follows. Redeeming a link we sent to that address is the proof a verification email would have been asking for.

Operation ID create_membership_membership_post

Parameters

No parameters.

Responses

201
Session
Successful Response
422
HTTPValidationError
Validation Error

Example request

curl -X POST 'http://localhost:8000/membership' \
  -H 'Content-Type: application/json' \
  -d '{
  "token": "<Token>",
  "password": "<Password>",
  "first_name": "string",
  "last_name": "string"
}'

Request body

MembershipRequest

{
  "token": "<Token>",
  "password": "<Password>",
  "first_name": "string",
  "last_name": "string"
}

Example response

{
  "access_token": "<Access Token>",
  "expires_in": 1,
  "user_id": "<User Id>",
  "organization_id": "<Organization Id>",
  "email": "<Email>",
  "role": "<Role>",
  "token_type": "Bearer"
}

auth

4 operations

API keys, and what the current credential is.

GET/keyAPI key

List API keys

Live keys for the organization, newest first. Never the key itself.

Operation ID list_keys_key_get

Parameters

No parameters.

Responses

200
Response List Keys Key Get
Successful Response

Example request

curl -X GET 'http://localhost:8000/key' \
  -H 'X-API-Key: $PLACESTACK_API_KEY'

Example response

[
  {
    "id": "<Id>",
    "name": "string",
    "key_prefix": "<Key Prefix>",
    "scopes": [
      "string"
    ],
    "usage_count": 1,
    "created_at": "<Created At>",
    "last_used_at": "string",
    "expires_at": "string"
  }
]
POST/keyAPI key

Mint an API key

Create a key and return it once.

Only a console session can mint one. A key that can mint keys is a key that never really gets revoked.

Operation ID create_key_key_post

Parameters

No parameters.

Responses

201
MintedKey
Successful Response
422
HTTPValidationError
Validation Error

Example request

curl -X POST 'http://localhost:8000/key' \
  -H 'X-API-Key: $PLACESTACK_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "<Name>",
  "scopes": [
    "string"
  ],
  "expires_in_days": 1
}'

Request body

CreateKeyRequest

{
  "name": "<Name>",
  "scopes": [
    "string"
  ],
  "expires_in_days": 1
}

Example response

{
  "id": "<Id>",
  "name": "string",
  "key_prefix": "<Key Prefix>",
  "scopes": [
    "string"
  ],
  "usage_count": 1,
  "created_at": "<Created At>",
  "key": "<Key>",
  "last_used_at": "string",
  "expires_at": "string"
}
DELETE/key/{key_id}API key

Revoke an API key

Revoke rather than delete, and only within your own organization.

The row stays so an audit entry written months ago still resolves to a name instead of a dangling id. Idempotent: revoking twice is not an error.

Operation ID revoke_key_key__key_id__delete

Parameters

path

key_idrequiredstring
No description.

Responses

204
empty
Successful Response
422
HTTPValidationError
Validation Error

Example request

curl -X DELETE 'http://localhost:8000/key/key_abc123' \
  -H 'X-API-Key: $PLACESTACK_API_KEY'
GET/me/actorAPI key

Describe the current credential

What this credential is, as the API sees it.

The fastest way for an integrator to find out why a call is being refused.

Operation ID whoami_me_actor_get

Parameters

No parameters.

Responses

200
Response Whoami Me Actor Get
Successful Response

Example request

curl -X GET 'http://localhost:8000/me/actor' \
  -H 'X-API-Key: $PLACESTACK_API_KEY'

Example response

{}

entitlement

1 operation

What an organization may do, and its credit balance.

GET/entitlementBearer token

Current Entitlements

Everything in force for the caller's organization.

Operation ID current_entitlements_entitlement_get

Parameters

No parameters.

Responses

200
Entitlements
Successful Response

Example request

curl -X GET 'http://localhost:8000/entitlement' \
  -H 'X-API-Key: $PLACESTACK_API_KEY'

Example response

{
  "organization_id": "<Organization Id>",
  "features": {
    "key": "string"
  },
  "credit_balance": 1
}

usage

2 operations

What an organization has spent, and on what.

GET/usageAPI key

What this organization has spent, and on what

Operation ID read_usage_usage_get

Parameters

query

daysinteger
How far back to look.

Responses

200
UsageSummary
Successful Response
422
HTTPValidationError
Validation Error

Example request

curl -X GET 'http://localhost:8000/usage' \
  -H 'X-API-Key: $PLACESTACK_API_KEY'

Example response

{
  "organization_id": "<Organization Id>",
  "since": "2026-09-13T12:00:00Z",
  "until": "2026-09-13T12:00:00Z",
  "requests": 1,
  "credits_spent": 1,
  "free_requests": 1,
  "credit_balance": 1,
  "included_credits": 1,
  "daily": [
    {
      "day": "2026-09-13T12:00:00Z",
      "requests": 1,
      "credits": 1
    }
  ],
  "by_endpoint": [
    {
      "name": "<Name>",
      "requests": 1,
      "credits": 1
    }
  ],
  "by_key": [
    {
      "name": "<Name>",
      "requests": 1,
      "credits": 1
    }
  ]
}
GET/creditAPI key

The balance, and every move that made it

The customer's own view of the same ledger the back office reads.

Deliberately the whole ledger and not a summary: "why is my balance 812" is a question they should be able to answer without asking us.

Operation ID read_credit_credit_get

Parameters

query

limitinteger
No description.

Responses

200
CreditView
Successful Response
422
HTTPValidationError
Validation Error

Example request

curl -X GET 'http://localhost:8000/credit' \
  -H 'X-API-Key: $PLACESTACK_API_KEY'

Example response

{
  "organization_id": "<Organization Id>",
  "balance": 1,
  "included_credits": 1,
  "ledger": [
    {
      "delta": 1,
      "reason": "<Reason>",
      "balance_after": 1,
      "created_at": "2026-09-13T12:00:00Z",
      "reference": "string"
    }
  ]
}

billing

5 operations

Plans, subscriptions, checkout and top-ups.

GET/planPublic

The plans on offer

Public: the pricing page and the console read the same list.

Operation ID list_plans_plan_get

Parameters

No parameters.

Responses

200
Response List Plans Plan Get
Successful Response

Example request

curl -X GET 'http://localhost:8000/plan'

Example response

[
  {
    "slug": "<Slug>",
    "name": "<Name>",
    "included_credits": 1,
    "signup_credits": 1,
    "watch_limit": 1,
    "purchasable": true
  }
]
GET/subscriptionAPI key

What this organization is on

Operation ID read_subscription_subscription_get

Parameters

No parameters.

Responses

200
Subscription
Successful Response

Example request

curl -X GET 'http://localhost:8000/subscription' \
  -H 'X-API-Key: $PLACESTACK_API_KEY'

Example response

{
  "organization_id": "<Organization Id>",
  "plan": "string",
  "plan_name": "string",
  "status": "<Status>",
  "included_credits": 1,
  "credit_balance": 1,
  "expiring_credits": 1,
  "billing_configured": true,
  "renews_at": "string",
  "cancel_at_period_end": false
}
POST/checkoutAPI key

Start a subscription

A Stripe Checkout session for a plan.

We never take card details, and the API never sees one. The organization id rides in client_reference_id so the webhook can attribute the payment without trusting anything the browser sends back.

Operation ID create_checkout_checkout_post

Parameters

No parameters.

Responses

200
Checkout
Successful Response
422
HTTPValidationError
Validation Error

Example request

curl -X POST 'http://localhost:8000/checkout' \
  -H 'X-API-Key: $PLACESTACK_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "plan": "<Plan>",
  "return_url": "string"
}'

Request body

CheckoutRequest

{
  "plan": "<Plan>",
  "return_url": "string"
}

Example response

{
  "url": "<Url>"
}
POST/topupAPI key

Buy more credits

A one-off Checkout for credits, outside the subscription.

The quantity is the credit count, so Stripe's per-unit price is the price of one credit and there is no second place where the maths could drift.

Operation ID create_topup_topup_post

Parameters

No parameters.

Responses

200
Checkout
Successful Response
422
HTTPValidationError
Validation Error

Example request

curl -X POST 'http://localhost:8000/topup' \
  -H 'X-API-Key: $PLACESTACK_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "credits": 1
}'

Request body

TopUpRequest

{
  "credits": 1
}

Example response

{
  "url": "<Url>"
}
POST/billing-portalAPI key

Manage card and invoices

Stripe's own portal, so we never build an invoice list or a card form.

Operation ID create_portal_billing_portal_post

Parameters

No parameters.

Responses

200
Checkout
Successful Response

Example request

curl -X POST 'http://localhost:8000/billing-portal' \
  -H 'X-API-Key: $PLACESTACK_API_KEY'

Example response

{
  "url": "<Url>"
}

oauth

4 operations

The OAuth 2.1 authorization server.

POST/oauth/registerBearer token

Register Client

Register a client against the caller's organization.

Adjuda leaves this endpoint public and takes the organization from the request body, which lets anyone who knows an org id plant a plausible-looking client in someone else's tenant — the setup for a consent-phishing screen. Here it requires a signed-in person and the org comes from their session.

Operation ID register_client_oauth_register_post

Parameters

No parameters.

Responses

201
Response Register Client Oauth Register Post
Successful Response
422
HTTPValidationError
Validation Error

Example request

curl -X POST 'http://localhost:8000/oauth/register' \
  -H 'X-API-Key: $PLACESTACK_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "client_name": "<Client Name>",
  "redirect_uris": [
    "string"
  ],
  "logo_uri": "string",
  "grant_types": [
    "string"
  ]
}'

Request body

RegisterClientRequest

{
  "client_name": "<Client Name>",
  "redirect_uris": [
    "string"
  ],
  "logo_uri": "string",
  "grant_types": [
    "string"
  ]
}

Example response

{}
GET/oauth/authorizePublic

Authorize

Validate the request, then hand the person to the console to decide.

Nothing is minted here. This endpoint's whole job is to refuse a malformed or dishonest request *before* a consent screen is drawn, so the screen a person sees is only ever one we would honour.

Operation ID authorize_oauth_authorize_get

Parameters

query

client_idrequiredstring
No description.
redirect_urirequiredstring
No description.
code_challengerequiredstring
No description.
response_typestring
No description.
code_challenge_methodstring
No description.
scopestring | null
No description.
statestring | null
No description.
resourcestring | null
No description.

Responses

200
unknown
Successful Response
422
HTTPValidationError
Validation Error

Example request

curl -X GET 'http://localhost:8000/oauth/authorize?client_id=value&redirect_uri=value&code_challenge=value'

Example response

"string"
POST/oauth/authorizeBearer token

Create Authorization Code

Mint an authorization code for the person who just approved.

Requires a console session, so the code — and every token that follows from it — is bound to a specific human rather than to the application that asked.

Operation ID create_authorization_code_oauth_authorize_post

Parameters

No parameters.

Responses

200
Response Create Authorization Code Oauth Authorize Post
Successful Response
422
HTTPValidationError
Validation Error

Example request

curl -X POST 'http://localhost:8000/oauth/authorize' \
  -H 'X-API-Key: $PLACESTACK_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "client_id": "<Client Id>",
  "redirect_uri": "<Redirect Uri>",
  "code_challenge": "<Code Challenge>",
  "code_challenge_method": "S256",
  "scope": "string",
  "resource": "string"
}'

Request body

ConsentRequest

{
  "client_id": "<Client Id>",
  "redirect_uri": "<Redirect Uri>",
  "code_challenge": "<Code Challenge>",
  "code_challenge_method": "S256",
  "scope": "string",
  "resource": "string"
}

Example response

{
  "key": "string"
}
POST/oauth/tokenPublic

Token

The token endpoint. Form-encoded, as OAuth requires.

Operation ID token_oauth_token_post

Parameters

No parameters.

Responses

200
Response Token Oauth Token Post
Successful Response
422
HTTPValidationError
Validation Error

Example request

curl -X POST 'http://localhost:8000/oauth/token' \
  -H 'Content-Type: application/json' \
  -d '{
  "grant_type": "<Grant Type>",
  "client_id": "<Client Id>",
  "code": "string",
  "code_verifier": "string",
  "redirect_uri": "string",
  "refresh_token": "string",
  "client_secret": "string"
}'

Request body

Body_token_oauth_token_post

{
  "grant_type": "<Grant Type>",
  "client_id": "<Client Id>",
  "code": "string",
  "code_verifier": "string",
  "redirect_uri": "string",
  "refresh_token": "string",
  "client_secret": "string"
}

Example response

{}

The document

Everything above is read from OpenAPI 3.1.0 version 0.0.0. When the contract changes, this page follows.

Download the OpenAPI document

Next

Look up an address

One address, the rules that reach it, and what is missing.