Settings

Per-org settings. ingestionPolicy: permissive | strict decides the fate of unclassified event/trait names (accept-and-flag vs quarantine review). eventRetentionDays is the ClickHouse TTL window; null keeps events forever. sendingPaused is the platform’s per-org pause: the org can read it, but only the operator sets it. This module is also the self-service home of the org’s two key families: ingestion API keys, which write events and reach nothing else, and deploy keys, which drive the release lifecycle and reach nothing else. Any member lists either; admins create and revoke them. Neither list shows the other family’s keys, and a revoke that names the other family’s key id is a 404. See the Keys guide.

GET /v1/settings/org

Fetch org settings

Auth: Clerk session token.

Response 200

{
  "data": {
    "environment": "development",
    "ingestionPolicy": "permissive",
    "eventRetentionDays": 1,
    "slug": "string",
    "name": "string"
  },
  "meta": {
    "requestId": "string",
    "nextCursor": "string",
    "hasMore": true
  }
}

Field	Type	Required	Constraints
data	object	yes
data.environment	“development” | “production”	yes
data.ingestionPolicy	“permissive” | “strict”	yes
data.eventRetentionDays	integer	yes	1 ≤ x ≤ 548
data.slug	string | null	yes
data.name	string | null	yes
meta	object	no
meta.requestId	string	no
meta.nextCursor	string | null	no
meta.hasMore	boolean	no

Errors follow the shared envelope and code table.

PATCH /v1/settings/org

Update org settings

Auth: Clerk session token.

Request body

{
  "data": {
    "ingestionPolicy": "permissive",
    "eventRetentionDays": 1
  }
}

Field	Type	Required	Constraints
data	object	yes
data.ingestionPolicy	“permissive” | “strict”	no
data.eventRetentionDays	integer	no	1 ≤ x ≤ 548

Response 200

{
  "data": {
    "environment": "development",
    "ingestionPolicy": "permissive",
    "eventRetentionDays": 1,
    "slug": "string",
    "name": "string"
  },
  "meta": {
    "requestId": "string",
    "nextCursor": "string",
    "hasMore": true
  }
}

Field	Type	Required	Constraints
data	object	yes
data.environment	“development” | “production”	yes
data.ingestionPolicy	“permissive” | “strict”	yes
data.eventRetentionDays	integer	yes	1 ≤ x ≤ 548
data.slug	string | null	yes
data.name	string | null	yes
meta	object	no
meta.requestId	string	no
meta.nextCursor	string | null	no
meta.hasMore	boolean	no

Errors follow the shared envelope and code table.

GET /v1/settings/api-keys

List org API keys

Auth: Clerk session token.

Query parameters

{
  "cursor": "string",
  "limit": 50
}

Field	Type	Required	Constraints
cursor	string	no
limit	integer	no	default 50; 1 ≤ x ≤ 100

Response 200

{
  "data": [
    {
      "id": "string",
      "name": "string",
      "createdAt": "2026-01-15T09:30:00.000Z",
      "createdBy": "string",
      "revoked": true,
      "revocationReason": "string",
      "expired": true,
      "expiresAt": "2026-01-15T09:30:00.000Z",
      "lastUsedAt": "2026-01-15T09:30:00.000Z"
    }
  ],
  "meta": {
    "requestId": "string",
    "nextCursor": "string",
    "hasMore": true
  }
}

Field	Type	Required	Constraints
data	object[]	yes
data[]	object	yes
data[].id	string	yes
data[].name	string	yes
data[].createdAt	string (date-time)	yes
data[].createdBy	string | null	yes
data[].revoked	boolean	yes
data[].revocationReason	string | null	yes
data[].expired	boolean	yes
data[].expiresAt	string (date-time) | null	yes
data[].lastUsedAt	string (date-time) | null	yes
meta	object	no
meta.requestId	string	no
meta.nextCursor	string | null	no
meta.hasMore	boolean	no

Errors follow the shared envelope and code table.

POST /v1/settings/api-keys

Create an org API key

Auth: Clerk session token.

Request body

{
  "data": {
    "name": "string"
  }
}

Field	Type	Required	Constraints
data	object	yes
data.name	string	yes	length 1–100

Response 201

{
  "data": {
    "id": "string",
    "name": "string",
    "createdAt": "2026-01-15T09:30:00.000Z",
    "createdBy": "string",
    "revoked": true,
    "revocationReason": "string",
    "expired": true,
    "expiresAt": "2026-01-15T09:30:00.000Z",
    "lastUsedAt": "2026-01-15T09:30:00.000Z",
    "secret": "string"
  },
  "meta": {
    "requestId": "string",
    "nextCursor": "string",
    "hasMore": true
  }
}

Field	Type	Required	Constraints
data	object	yes
data.id	string	yes
data.name	string	yes
data.createdAt	string (date-time)	yes
data.createdBy	string | null	yes
data.revoked	boolean	yes
data.revocationReason	string | null	yes
data.expired	boolean	yes
data.expiresAt	string (date-time) | null	yes
data.lastUsedAt	string (date-time) | null	yes
data.secret	string	yes
meta	object	no
meta.requestId	string	no
meta.nextCursor	string | null	no
meta.hasMore	boolean	no

Errors follow the shared envelope and code table.

GET /v1/settings/deploy-keys

List org deploy keys

Auth: Clerk session token.

Query parameters

{
  "cursor": "string",
  "limit": 50
}

Field	Type	Required	Constraints
cursor	string	no
limit	integer	no	default 50; 1 ≤ x ≤ 100

Response 200

{
  "data": [
    {
      "id": "string",
      "name": "string",
      "createdAt": "2026-01-15T09:30:00.000Z",
      "createdBy": "string",
      "revoked": true,
      "revocationReason": "string",
      "expired": true,
      "expiresAt": "2026-01-15T09:30:00.000Z",
      "lastUsedAt": "2026-01-15T09:30:00.000Z"
    }
  ],
  "meta": {
    "requestId": "string",
    "nextCursor": "string",
    "hasMore": true
  }
}

Field	Type	Required	Constraints
data	object[]	yes
data[]	object	yes
data[].id	string	yes
data[].name	string	yes
data[].createdAt	string (date-time)	yes
data[].createdBy	string | null	yes
data[].revoked	boolean	yes
data[].revocationReason	string | null	yes
data[].expired	boolean	yes
data[].expiresAt	string (date-time) | null	yes
data[].lastUsedAt	string (date-time) | null	yes
meta	object	no
meta.requestId	string	no
meta.nextCursor	string | null	no
meta.hasMore	boolean	no

Errors follow the shared envelope and code table.

POST /v1/settings/deploy-keys

Create an org deploy key

Auth: Clerk session token.

Request body

{
  "data": {
    "name": "string"
  }
}

Field	Type	Required	Constraints
data	object	yes
data.name	string	yes	length 1–100

Response 201

{
  "data": {
    "id": "string",
    "name": "string",
    "createdAt": "2026-01-15T09:30:00.000Z",
    "createdBy": "string",
    "revoked": true,
    "revocationReason": "string",
    "expired": true,
    "expiresAt": "2026-01-15T09:30:00.000Z",
    "lastUsedAt": "2026-01-15T09:30:00.000Z",
    "secret": "string"
  },
  "meta": {
    "requestId": "string",
    "nextCursor": "string",
    "hasMore": true
  }
}

Field	Type	Required	Constraints
data	object	yes
data.id	string	yes
data.name	string	yes
data.createdAt	string (date-time)	yes
data.createdBy	string | null	yes
data.revoked	boolean	yes
data.revocationReason	string | null	yes
data.expired	boolean	yes
data.expiresAt	string (date-time) | null	yes
data.lastUsedAt	string (date-time) | null	yes
data.secret	string	yes
meta	object	no
meta.requestId	string	no
meta.nextCursor	string | null	no
meta.hasMore	boolean	no

Errors follow the shared envelope and code table.

POST /v1/settings/deploy-keys/{id}/revoke

Revoke an org deploy key

Auth: Clerk session token.

Request body

{
  "data": {
    "revocationReason": "string"
  }
}

Field	Type	Required	Constraints
data	object	yes
data.revocationReason	string	no	length 1–500

Response 200

{
  "data": {
    "id": "string",
    "name": "string",
    "createdAt": "2026-01-15T09:30:00.000Z",
    "createdBy": "string",
    "revoked": true,
    "revocationReason": "string",
    "expired": true,
    "expiresAt": "2026-01-15T09:30:00.000Z",
    "lastUsedAt": "2026-01-15T09:30:00.000Z"
  },
  "meta": {
    "requestId": "string",
    "nextCursor": "string",
    "hasMore": true
  }
}

Field	Type	Required	Constraints
data	object	yes
data.id	string	yes
data.name	string	yes
data.createdAt	string (date-time)	yes
data.createdBy	string | null	yes
data.revoked	boolean	yes
data.revocationReason	string | null	yes
data.expired	boolean	yes
data.expiresAt	string (date-time) | null	yes
data.lastUsedAt	string (date-time) | null	yes
meta	object	no
meta.requestId	string	no
meta.nextCursor	string | null	no
meta.hasMore	boolean	no

Errors follow the shared envelope and code table.

POST /v1/settings/api-keys/{id}/revoke

Revoke an org API key

Auth: Clerk session token.

Request body

{
  "data": {
    "revocationReason": "string"
  }
}

Field	Type	Required	Constraints
data	object	yes
data.revocationReason	string	no	length 1–500

Response 200

{
  "data": {
    "id": "string",
    "name": "string",
    "createdAt": "2026-01-15T09:30:00.000Z",
    "createdBy": "string",
    "revoked": true,
    "revocationReason": "string",
    "expired": true,
    "expiresAt": "2026-01-15T09:30:00.000Z",
    "lastUsedAt": "2026-01-15T09:30:00.000Z"
  },
  "meta": {
    "requestId": "string",
    "nextCursor": "string",
    "hasMore": true
  }
}

Field	Type	Required	Constraints
data	object	yes
data.id	string	yes
data.name	string	yes
data.createdAt	string (date-time)	yes
data.createdBy	string | null	yes
data.revoked	boolean	yes
data.revocationReason	string | null	yes
data.expired	boolean	yes
data.expiresAt	string (date-time) | null	yes
data.lastUsedAt	string (date-time) | null	yes
meta	object	no
meta.requestId	string	no
meta.nextCursor	string | null	no
meta.hasMore	boolean	no

Errors follow the shared envelope and code table.