API reference

Shared capabilities for Trida products: Core (projects, keys, webhooks), Notify, Pay, Billing, AI. One API key per project; every key is scoped. Version 0.1.0. Generated from the OpenAPI contract: it cannot drift from the API.

Base URLs: https://api.trida.lu (Production), https://api-dev.trida.lu (Development). Authenticate with x-api-key.

platform

GET `/api/health`

Liveness and readiness of this process

No scope required beyond a valid key.

Responses

Status	Meaning	Body
`200`	Healthy	Health
`503`	Database unreachable	Health

Example

curl -X GET "https://api.trida.lu/api/health" \
  -H "x-api-key: $TRIDA_API_KEY"

core

GET `/core/v1/projects/me`

The project the API key belongs to, with its theme and languages

Required scope: projects:read

Responses

Status	Meaning	Body
`200`	The project	ProjectMe
`401`	API key missing, invalid or revoked	PlatformError
`403`	The key lacks the projects:read scope	PlatformError
`404`	The project no longer exists	PlatformError

Example

curl -X GET "https://api.trida.lu/core/v1/projects/me" \
  -H "x-api-key: $TRIDA_API_KEY"

POST `/core/v1/subjects/erase`

Erase or anonymize a person in every capability of the project, keeping what the law requires to keep

Required scope: subjects:erase

Parameters

Name	In	Type	Required	Notes
`idempotency-key`	header	string	yes

Request body

object

Field	Type	Required	Notes
`subject`	object	yes

Responses

Status	Meaning	Body
`200`	What each capability erased; the list is empty while no capability holds data about people	SubjectErased
`400`	The body or the Idempotency-Key is not valid	PlatformError
`401`	API key missing, invalid or revoked	PlatformError
`403`	The key lacks the subjects:erase scope	PlatformError
`409`	A request with this Idempotency-Key is still being processed	PlatformError
`422`	This Idempotency-Key was already used with a different request	PlatformError

Example

curl -X POST "https://api.trida.lu/core/v1/subjects/erase" \
  -H "x-api-key: $TRIDA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{"subject":{"type":"phone","value":"string"}}'

GET `/core/v1/usage`

Usage of the project by day, capability and metric, and its daily limits (UTC days, at most 92)

Required scope: usage:read

Parameters

Name	In	Type	Required	Notes
`from`	query	string	no
`to`	query	string	no

Responses

Status	Meaning	Body
`200`	The usage	Usage
`400`	A date is not YYYY-MM-DD, from is after to, or the range exceeds 92 days	PlatformError
`401`	API key missing, invalid or revoked	PlatformError
`403`	The key lacks the usage:read scope	PlatformError

Example

curl -X GET "https://api.trida.lu/core/v1/usage" \
  -H "x-api-key: $TRIDA_API_KEY"

GET `/core/v1/webhook-endpoints`

List the endpoints of the project, never a secret

Required scope: webhooks:read

Responses

Status	Meaning	Body
`200`	The endpoints	WebhookEndpointList
`401`	API key missing, invalid or revoked	PlatformError
`403`	The key lacks the webhooks scope this route needs	PlatformError

Example

curl -X GET "https://api.trida.lu/core/v1/webhook-endpoints" \
  -H "x-api-key: $TRIDA_API_KEY"

POST `/core/v1/webhook-endpoints`

Declare an endpoint that receives the events of the project; the secret is returned once

Required scope: webhooks:write

Parameters

Name	In	Type	Required	Notes
`idempotency-key`	header	string	yes

Request body

object

Field	Type	Required	Notes
`url`	string (uri)	yes	max length 2048
`eventTypes`	array of string	yes

Responses

Status	Meaning	Body
`201`	The endpoint and its HMAC secret, in clear this one time	WebhookEndpointCreated
`400`	The body or the Idempotency-Key is not valid, the address is not a public HTTPS address, or the project already has 20 endpoints	PlatformError
`401`	API key missing, invalid or revoked	PlatformError
`403`	The key lacks the webhooks scope this route needs	PlatformError
`409`	A request with this Idempotency-Key is still being processed	PlatformError
`422`	This Idempotency-Key was already used with a different request	PlatformError

Example

curl -X POST "https://api.trida.lu/core/v1/webhook-endpoints" \
  -H "x-api-key: $TRIDA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{"url":"https://example.com/webhooks/trida","eventTypes":["string"]}'

DELETE `/core/v1/webhook-endpoints/{id}`

Delete an endpoint and its secrets

Required scope: webhooks:write

Parameters

Name	In	Type	Required	Notes
`id`	path	string (uuid)	yes
`idempotency-key`	header	string	yes

Responses

Status	Meaning	Body
`204`	Deleted
`400`	The Idempotency-Key is missing or not valid	PlatformError
`401`	API key missing, invalid or revoked	PlatformError
`403`	The key lacks the webhooks scope this route needs	PlatformError
`404`	No such endpoint in this project	PlatformError
`409`	A request with this Idempotency-Key is still being processed	PlatformError
`422`	This Idempotency-Key was already used with a different request	PlatformError

Example

curl -X DELETE "https://api.trida.lu/core/v1/webhook-endpoints/$ID" \
  -H "x-api-key: $TRIDA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

POST `/core/v1/webhook-endpoints/{id}/rotate-secret`

Make a new secret the active one; the previous one keeps signing until it is retired, so nothing is interrupted

Required scope: webhooks:write

Parameters

Name	In	Type	Required	Notes
`id`	path	string (uuid)	yes
`idempotency-key`	header	string	yes

Responses

Status	Meaning	Body
`200`	The new secret, in clear this one time	WebhookSecretRotated
`400`	The Idempotency-Key is missing or not valid	PlatformError
`401`	API key missing, invalid or revoked	PlatformError
`403`	The key lacks the webhooks scope this route needs	PlatformError
`404`	No such endpoint in this project	PlatformError
`409`	A request with this Idempotency-Key is still being processed	PlatformError
`422`	This Idempotency-Key was already used with a different request	PlatformError

Example

curl -X POST "https://api.trida.lu/core/v1/webhook-endpoints/$ID/rotate-secret" \
  -H "x-api-key: $TRIDA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

POST `/core/v1/webhook-endpoints/{id}/retire-previous-secret`

End a rotation: the previous secret stops signing, only the active one remains

Required scope: webhooks:write

Parameters

Name	In	Type	Required	Notes
`id`	path	string (uuid)	yes
`idempotency-key`	header	string	yes

Responses

Status	Meaning	Body
`200`	The endpoint	WebhookEndpoint
`400`	The Idempotency-Key is missing or not valid, or there is no previous secret	PlatformError
`401`	API key missing, invalid or revoked	PlatformError
`403`	The key lacks the webhooks scope this route needs	PlatformError
`404`	No such endpoint in this project	PlatformError
`409`	A request with this Idempotency-Key is still being processed	PlatformError
`422`	This Idempotency-Key was already used with a different request	PlatformError

Example

curl -X POST "https://api.trida.lu/core/v1/webhook-endpoints/$ID/retire-previous-secret" \
  -H "x-api-key: $TRIDA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

POST `/core/v1/events/{id}/replay`

Replay an event to the active endpoints subscribed to its type: same eventId, new deliveries, fresh signature

Required scope: webhooks:write

Parameters

Name	In	Type	Required	Notes
`id`	path	string (uuid)	yes
`idempotency-key`	header	string	yes

Responses

Status	Meaning	Body
`200`	How many deliveries were created, one per active subscribed endpoint (0 if none)	WebhookReplayResult
`400`	The Idempotency-Key is missing or not valid, or the event is still being dispatched for the first time	PlatformError
`401`	API key missing, invalid or revoked	PlatformError
`403`	The key lacks the webhooks scope this route needs	PlatformError
`404`	No such event in this project	PlatformError
`409`	A request with this Idempotency-Key is still being processed	PlatformError
`422`	This Idempotency-Key was already used with a different request	PlatformError

Example

curl -X POST "https://api.trida.lu/core/v1/events/$ID/replay" \
  -H "x-api-key: $TRIDA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

POST `/core/v1/webhook-endpoints/{id}/test`

Send a signed test event (core.webhook.test) to this endpoint only, to try reception and signature verification

Required scope: webhooks:write

Parameters

Name	In	Type	Required	Notes
`id`	path	string (uuid)	yes
`idempotency-key`	header	string	yes

Responses

Status	Meaning	Body
`200`	The test event was queued; it is delivered like any other event, signed with the active secrets	WebhookTestSent
`400`	The Idempotency-Key is missing or not valid	PlatformError
`401`	API key missing, invalid or revoked	PlatformError
`403`	The key lacks the webhooks scope this route needs	PlatformError
`404`	No such endpoint in this project	PlatformError
`409`	A request with this Idempotency-Key is still being processed	PlatformError
`422`	This Idempotency-Key was already used with a different request	PlatformError

Example

curl -X POST "https://api.trida.lu/core/v1/webhook-endpoints/$ID/test" \
  -H "x-api-key: $TRIDA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Schemas

`Health`

Field	Type	Required
`status`	`"ok"` \| `"degraded"`	yes
`env`	`"local"` \| `"dev"` \| `"prod"`	yes
`version`	string	yes
`commit`	string	yes
`db`	`"up"` \| `"down"`	yes
`queue`	`"up"` \| `"idle"`	yes
`queueDead`	integer	yes
`queueFailed24h`	integer	yes
`webhooksDead24h`	integer	yes
`breakers`	array of object	yes
`lastMigration`	string or null	yes

{
  "status": "ok",
  "env": "local",
  "version": "string",
  "commit": "string",
  "db": "up",
  "queue": "up",
  "queueDead": 0,
  "queueFailed24h": 0,
  "webhooksDead24h": 0,
  "breakers": [
    {
      "provider": "string",
      "state": "closed"
    }
  ],
  "lastMigration": "string"
}

`ProjectMe`

Field	Type	Required
`id`	string (uuid)	yes
`slug`	string	yes
`name`	string	yes
`mode`	`"test"` \| `"live"`	yes
`languages`	array of string	yes
`theme`	object	yes

{
  "id": "2c4d0f3a-7b2e-4a1e-9a7f-1c2d3e4f5a6b",
  "slug": "demo",
  "name": "Démo",
  "mode": "test",
  "languages": [
    "fr",
    "en"
  ],
  "theme": {
    "logoUrl": null,
    "primary": "#23306b",
    "accent": "#c5e6f4",
    "background": "#ffffff",
    "text": "#152f4e"
  }
}

`PlatformError`

Field	Type	Required	Notes
`code`	`"API_KEY_MISSING"` \| `"API_KEY_INVALID"` \| `"API_KEY_REVOKED"` \| `"SCOPE_MISSING"` \| `"PROJECT_NOT_FOUND"` \| `"NOT_FOUND"` \| `"VALIDATION_FAILED"` \| `"IDEMPOTENCY_KEY_MISSING"` \| `"IDEMPOTENCY_BODY_MISMATCH"` \| `"IDEMPOTENCY_IN_PROGRESS"` \| `"QUOTA_EXCEEDED"` \| `"RATE_LIMITED"` \| `"PROVIDER_ERROR"` \| `"PROVIDER_TIMEOUT"` \| `"PROVIDER_UNAVAILABLE"` \| `"OVERLOADED"` \| `"TIMEOUT"` \| `"INTERNAL"`	yes
`message`	string	yes

{
  "code": "API_KEY_INVALID",
  "message": "The API key is not valid."
}

`SubjectErased`

Field	Type	Required	Notes
`capabilities`	array of object	yes

{
  "capabilities": [
    {
      "capability": "string",
      "erased": 0
    }
  ]
}

`Usage`

Field	Type	Required	Notes
`from`	string	yes	pattern `^\d{4}-\d{2}-\d{2}$`
`to`	string	yes	pattern `^\d{4}-\d{2}-\d{2}$`
`data`	array of object	yes
`limits`	array of object	yes

{
  "from": "string",
  "to": "string",
  "data": [
    {
      "day": "string",
      "capability": "string",
      "metric": "string",
      "count": 0
    }
  ],
  "limits": [
    {
      "capability": "string",
      "metric": "string",
      "dailyLimit": 0
    }
  ]
}

`WebhookEndpointCreated`

Field	Type	Required
`id`	string (uuid)	yes
`url`	string	yes
`eventTypes`	array of string	yes
`active`	boolean	yes
`hasPreviousSecret`	boolean	yes
`createdAt`	string (date-time)	yes
`secret`	string	yes

{
  "id": "11111111-2222-4333-8444-555555555555",
  "url": "string",
  "eventTypes": [
    "string"
  ],
  "active": true,
  "hasPreviousSecret": true,
  "createdAt": "2026-10-18T10:00:00.000Z",
  "secret": "string"
}

`WebhookEndpointList`

Field	Type	Required	Notes
`data`	array of object	yes

{
  "data": [
    {
      "id": "11111111-2222-4333-8444-555555555555",
      "url": "string",
      "eventTypes": [
        "string"
      ],
      "active": true,
      "hasPreviousSecret": true,
      "createdAt": "2026-10-18T10:00:00.000Z"
    }
  ]
}

`WebhookSecretRotated`

Field	Type	Required	Notes
`id`	string (uuid)	yes
`secret`	string	yes

{
  "id": "11111111-2222-4333-8444-555555555555",
  "secret": "string"
}

`WebhookEndpoint`

Field	Type	Required
`id`	string (uuid)	yes
`url`	string	yes
`eventTypes`	array of string	yes
`active`	boolean	yes
`hasPreviousSecret`	boolean	yes
`createdAt`	string (date-time)	yes

{
  "id": "11111111-2222-4333-8444-555555555555",
  "url": "string",
  "eventTypes": [
    "string"
  ],
  "active": true,
  "hasPreviousSecret": true,
  "createdAt": "2026-10-18T10:00:00.000Z"
}

`WebhookReplayResult`

Field	Type	Required	Notes
`eventId`	string (uuid)	yes
`deliveries`	integer	yes	min 0

{
  "eventId": "11111111-2222-4333-8444-555555555555",
  "deliveries": 0
}

`WebhookTestSent`

Field	Type	Required	Notes
`eventId`	string (uuid)	yes
`endpointId`	string (uuid)	yes

{
  "eventId": "11111111-2222-4333-8444-555555555555",
  "endpointId": "11111111-2222-4333-8444-555555555555"
}

API reference

platform

GET /api/health

Responses

Example

core

GET /core/v1/projects/me

Responses

Example

POST /core/v1/subjects/erase

Parameters

Request body

Responses

Example

GET /core/v1/usage

Parameters

Responses

Example

GET /core/v1/webhook-endpoints

Responses

Example

POST /core/v1/webhook-endpoints

Parameters

Request body

Responses

Example

DELETE /core/v1/webhook-endpoints/{id}

Parameters

Responses

Example

POST /core/v1/webhook-endpoints/{id}/rotate-secret

Parameters

Responses

Example

POST /core/v1/webhook-endpoints/{id}/retire-previous-secret

Parameters

Responses

Example

POST /core/v1/events/{id}/replay

Parameters

Responses

Example

POST /core/v1/webhook-endpoints/{id}/test

Parameters

Responses

Example

Schemas

Health

ProjectMe

PlatformError

SubjectErased

Usage

WebhookEndpointCreated

WebhookEndpointList

WebhookSecretRotated

WebhookEndpoint

WebhookReplayResult

WebhookTestSent

GET `/api/health`

GET `/core/v1/projects/me`

POST `/core/v1/subjects/erase`

GET `/core/v1/usage`

GET `/core/v1/webhook-endpoints`

POST `/core/v1/webhook-endpoints`

DELETE `/core/v1/webhook-endpoints/{id}`

POST `/core/v1/webhook-endpoints/{id}/rotate-secret`

POST `/core/v1/webhook-endpoints/{id}/retire-previous-secret`

POST `/core/v1/events/{id}/replay`

POST `/core/v1/webhook-endpoints/{id}/test`

`Health`

`ProjectMe`

`PlatformError`

`SubjectErased`

`Usage`

`WebhookEndpointCreated`

`WebhookEndpointList`

`WebhookSecretRotated`

`WebhookEndpoint`

`WebhookReplayResult`

`WebhookTestSent`