Star
API reference

Projects, keys and sessions

Project management runs with the admin key (ADMIN_API_KEY) or a dashboard session. Project keys can't reach these routes, and they aren't rate-limited.

Create a project

POST/v1/projects

Auth: Admin key or a dashboard session. Project keys are rejected.

Creates a project and its first key, with the admin role. The key is returned once.

Body

FieldTypeRequiredDescription
namestringyes

Responses

{
  "id": "b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "apiKey": "nk_live_3f9c2a7e1b5d8f04c6a9e2b7d1f3c5a8e0b4d6f2a9c1e7b3d5f8a0c2e4b6d9f1"
}
{
  "error": "validation_error",
  "issues": [
    {
      "expected": "string",
      "code": "invalid_type",
      "path": [
        "name"
      ],
      "message": "Invalid input: expected string, received undefined"
    }
  ]
}
Common errors (401, 403, 400, 413, 500)
{
  "error": "unauthorized",
  "message": "Missing admin token"
}
{
  "error": "unauthorized",
  "message": "Invalid admin token"
}
{
  "error": "forbidden",
  "message": "Session is read-only"
}
{
  "error": "malformed_json",
  "message": "malformed_json"
}
{
  "error": "payload_too_large",
  "message": "payload_too_large"
}
{
  "error": "internal_error"
}

Example

curl -X POST http://localhost:3000/v1/projects \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "production" }'

List projects

GET/v1/projects

Auth: Admin key or a dashboard session. Project keys are rejected.

Newest first. null limits use the server defaults.

Responses

{
  "projects": [
    {
      "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "name": "staging",
      "rateLimitRpm": 6000,
      "throttleLimit": 0,
      "throttleWindowHours": 1,
      "createdAt": "2026-11-01T09:00:00.000Z"
    },
    {
      "id": "b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "production",
      "rateLimitRpm": null,
      "throttleLimit": null,
      "throttleWindowHours": null,
      "createdAt": "2026-10-02T08:30:00.000Z"
    }
  ]
}
{
  "projects": []
}
Common errors (401, 500)
{
  "error": "unauthorized",
  "message": "Missing admin token"
}
{
  "error": "unauthorized",
  "message": "Invalid admin token"
}
{
  "error": "internal_error"
}

Example

curl http://localhost:3000/v1/projects -H "Authorization: Bearer $ADMIN_API_KEY"
const { projects } = await admin.listProjects();

admin is a NotifkitClient created with the admin key.

Update project limits

PATCH/v1/projects/{id}

Auth: Admin key or a dashboard session. Project keys are rejected.

Applies on the next request or notification. null restores the default. Send at least one field.

Path parameters

NameTypeDescription
idstringProject id.

Body

FieldTypeRequiredDescription
rateLimitRpmnumber or nullnoAPI requests per minute. Default 600.
throttleLimitnumber or nullnoMessages per user per window. Default RATE_LIMIT_PER_HOUR (100). 0 stops every non-critical send.
throttleWindowHoursnumber or nullnoWindow length. Default 1.

Responses

{
  "id": "b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}
{
  "error": "validation_error",
  "issues": [
    {
      "path": "rateLimitRpm",
      "message": "Invalid input: expected number, received string"
    }
  ]
}
{
  "error": "project_not_found"
}
{
  "error": "internal_error"
}
Common errors (401, 403, 400, 413, 500)
{
  "error": "unauthorized",
  "message": "Missing admin token"
}
{
  "error": "unauthorized",
  "message": "Invalid admin token"
}
{
  "error": "forbidden",
  "message": "Session is read-only"
}
{
  "error": "malformed_json",
  "message": "malformed_json"
}
{
  "error": "payload_too_large",
  "message": "payload_too_large"
}
{
  "error": "internal_error"
}

Example

curl -X PATCH http://localhost:3000/v1/projects/b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "rateLimitRpm": 6000 }'
await admin.updateProject(projectId, { rateLimitRpm: 6000 });

Delete a project

DELETE/v1/projects/{id}

Auth: Admin key or a dashboard session. Project keys are rejected.

Deletes the project with its users, contacts, suppressions, delivery log and workflows. It can't be undone.

Path parameters

NameTypeDescription
idstringProject id.

Responses

No body.
{
  "error": "project_not_found"
}
Common errors (401, 403, 500)
{
  "error": "unauthorized",
  "message": "Missing admin token"
}
{
  "error": "unauthorized",
  "message": "Invalid admin token"
}
{
  "error": "forbidden",
  "message": "Session is read-only"
}
{
  "error": "internal_error"
}

Example

curl -X DELETE http://localhost:3000/v1/projects/b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d -H "Authorization: Bearer $ADMIN_API_KEY"
await admin.deleteProject(projectId);

Create an API key

POST/v1/projects/{id}/keys

Auth: Admin key or a dashboard session. Project keys are rejected.

The key is returned once. Use read_only for dashboards and reporting. A missing or unknown role creates an admin key rather than failing.

Path parameters

NameTypeDescription
idstringProject id.

Body

FieldTypeRequiredDescription
rolestringnoadmin (default) or read_only.

Responses

{
  "id": "8d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
  "apiKey": "nk_live_a71b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b",
  "role": "read_only"
}
{
  "error": "project_not_found"
}
Common errors (401, 403, 400, 413, 500)
{
  "error": "unauthorized",
  "message": "Missing admin token"
}
{
  "error": "unauthorized",
  "message": "Invalid admin token"
}
{
  "error": "forbidden",
  "message": "Session is read-only"
}
{
  "error": "malformed_json",
  "message": "malformed_json"
}
{
  "error": "payload_too_large",
  "message": "payload_too_large"
}
{
  "error": "internal_error"
}

Example

curl -X POST http://localhost:3000/v1/projects/b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d/keys \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "role": "read_only" }'
const { apiKey } = await admin.createProjectKey(projectId, { role: "read_only" });

List API keys

GET/v1/projects/{id}/keys

Auth: Admin key or a dashboard session. Project keys are rejected.

Ids and roles only, newest first. Secrets are never returned again. An unknown project returns an empty list.

Path parameters

NameTypeDescription
idstringProject id.

Responses

{
  "keys": [
    {
      "id": "8d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
      "role": "read_only",
      "createdAt": "2026-11-17T09:12:00.000Z"
    },
    {
      "id": "1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
      "role": "admin",
      "createdAt": "2026-10-02T08:30:00.000Z"
    }
  ]
}
{
  "error": "project_not_found"
}
Common errors (401, 500)
{
  "error": "unauthorized",
  "message": "Missing admin token"
}
{
  "error": "unauthorized",
  "message": "Invalid admin token"
}
{
  "error": "internal_error"
}

Example

curl http://localhost:3000/v1/projects/b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d/keys -H "Authorization: Bearer $ADMIN_API_KEY"
const { keys } = await admin.listProjectKeys(projectId);

Revoke an API key

DELETE/v1/projects/{id}/keys/{keyId}

Auth: Admin key or a dashboard session. Project keys are rejected.

Takes effect immediately on every API process.

Path parameters

NameTypeDescription
idstringProject id.
keyIdstringKey id.

Responses

No body.
{
  "error": "key_not_found"
}
Common errors (401, 403, 500)
{
  "error": "unauthorized",
  "message": "Missing admin token"
}
{
  "error": "unauthorized",
  "message": "Invalid admin token"
}
{
  "error": "forbidden",
  "message": "Session is read-only"
}
{
  "error": "internal_error"
}

Example

curl -X DELETE http://localhost:3000/v1/projects/b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d/keys/KEY_ID -H "Authorization: Bearer $ADMIN_API_KEY"
await admin.deleteProjectKey(projectId, keyId);

Dashboard sessions

The dashboard logs in with these. Users come from ADMIN_EMAIL and ADMIN_PASSWORD. A session token works like the admin key for 7 days.

Log in

POST/v1/auth/login

Auth: None.

Body

FieldTypeRequiredDescription
identifierstringyesEmail or username.
passwordstringyes

Responses

{
  "token": "nk_sess_9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c2b1a0f9e8d",
  "user": {
    "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
    "email": "[email protected]",
    "username": "you",
    "role": "superadmin"
  },
  "expiresAt": 1732442400000
}
{
  "error": "validation_error",
  "issues": [
    {
      "path": "identifier",
      "message": "Identifier (email or username) is required"
    },
    {
      "path": "password",
      "message": "Password is required"
    }
  ]
}
{
  "error": "unauthorized",
  "message": "Invalid credentials"
}
{
  "error": "too_many_requests",
  "message": "Too many login attempts. Please try again later."
}
Common errors (400, 413, 500)
{
  "error": "malformed_json",
  "message": "malformed_json"
}
{
  "error": "payload_too_large",
  "message": "payload_too_large"
}
{
  "error": "internal_error"
}

Example

curl -X POST http://localhost:3000/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "identifier": "[email protected]", "password": "…" }'

Current session

GET/v1/auth/me

Auth: A dashboard session token.

Responses

{
  "user": {
    "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
    "email": "[email protected]",
    "username": "you",
    "role": "superadmin"
  }
}
{
  "error": "unauthorized",
  "message": "Invalid or expired session"
}
{
  "error": "unauthorized",
  "message": "Missing token"
}
Common errors (401, 429, 500)
{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}
{
  "error": "too_many_requests",
  "message": "Project rate limit exceeded (max 600 req/min)"
}
{
  "error": "internal_error"
}

Example

curl http://localhost:3000/v1/auth/me -H "Authorization: Bearer $SESSION"

Log out

POST/v1/auth/logout

Auth: A dashboard session token.

Ends the session in the header. Allowed for read-only sessions.

Responses

200 OK Logged out, or there was no session to end.

{
  "message": "Logged out successfully"
}
Common errors (401, 429, 500)
{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}
{
  "error": "too_many_requests",
  "message": "Project rate limit exceeded (max 600 req/min)"
}
{
  "error": "internal_error"
}

Example

curl -X POST http://localhost:3000/v1/auth/logout -H "Authorization: Bearer $SESSION"