> ## Documentation Index
> Fetch the complete documentation index at: https://engineering.unkey.com/llms.txt
> Use this file to discover all available pages before exploring further.

# RPC-style API

> Action-oriented API design

Unkey v2 APIs use an RPC-style design that focuses on actions rather than
resources. New v2 endpoints must follow this pattern unless an explicit design
review accepts an exception.

```plaintext theme={"theme":"kanagawa-wave"}
https://api.unkey.com/v2/{service}.{procedure}
```

Examples:

* `POST /v2/keys.createKey`
* `POST /v2/ratelimit.limit`

## HTTP methods

All v2 operations use `POST`, except liveness and health endpoints. This keeps
request patterns consistent and lets every operation accept a typed JSON body.

Don't add REST-style resource routes to v2. Use `POST /v2/{service}.{procedure}`
for reads, writes, list operations, and command-style actions.

## Request format

* Use POST
* Include `Content-Type: application/json`
* Include `Authorization` header
* Send parameters as JSON in the request body

```bash theme={"theme":"kanagawa-wave"}
curl -X POST "https://api.unkey.com/v2/keys.createKey" \
  -H "Authorization: Bearer root_1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "apiId": "api_1234",
    "name": "Production API Key"
  }'
```

## Service namespaces

* keys
* apis
* ratelimit
* analytics
* identities
* permissions

## Operation names

Endpoint names use `{service}.{procedure}`. The OpenAPI `operationId` must match
the endpoint name so docs, SDKs, and agents see the same action name.

Use procedure names that describe the action from the caller's perspective:

* `createApi`
* `getKey`
* `listRoles`
* `updateIdentity`
* `deletePermission`
* `addPermissions`
* `removeRoles`
* `setOverride`

Prefer established verbs before adding a new verb. If a new verb is necessary,
document the behavior before adding endpoints that use it.

## Verb meanings

RPC APIs rely on verb consistency. Use these meanings for v2 procedures:

* `create`: create a new resource. If the resource already exists, return a
  conflict or document the idempotent behavior explicitly.
* `get`: read one resource.
* `list`: read a collection. Use pagination when the collection can grow.
* `update`: partially update a resource using three-state update semantics.
* `delete`: remove, invalidate, or tombstone a resource. Document soft-delete
  and hard-delete behavior explicitly.
* `add`: incrementally add members to a collection. Adding an existing member
  must be idempotent.
* `remove`: incrementally remove members from a collection. Removing a missing
  member must be idempotent.
* `set`: replace or upsert a singular configuration object or collection.
  Document whether omitted members are removed.

Domain verbs such as `verify`, `limit`, `exchange`, `reroll`, and `migrate` are
allowed when the standard verbs don't describe the operation clearly. Domain
verbs must document side effects and idempotency.

## Benefits

* Clear intent in endpoint names
* Natural mapping to code and user intent
* Better support for complex operations
* Flexible request structures