Tellagen
API Reference

API Reference

The Tellagen API lets you manage incidents, services, teams, and custom fields programmatically.

Base URL

https://{company}.api.tellagen.com/api/v1/

Replace {company} with your company subdomain.

Content type

All requests and responses use application/json.

Rate limits

API requests are rate-limited per token. If you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header.

Authentication

Authenticate by including an API token in the Authorization header.

bash
curl 'https://acme.api.tellagen.com/api/v1/incidents' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN'

Create API tokens in Settings > API Keys. Tokens start with the tllg_ prefix and are only shown once at creation time.

Scopes

Each API token is granted one or more scopes. A request will return 403 Forbidden if the token lacks the required scope.

ScopeDescription
incidents:readList and retrieve incidents
incidents:writeCreate and update incidents and timeline events
services:readList and retrieve services
services:writeCreate, update, and archive services
teams:readList and retrieve teams and members
teams:writeCreate, update, and archive teams; manage members
custom_fields:readList and retrieve custom field definitions and values
custom_fields:writeCreate, update, and archive custom fields; set incident field values

Errors

Errors return a JSON object with a message field.

json
{
  "message": "service name is required"
}
StatusMeaning
400Bad Request — invalid input or missing required fields
401Unauthorized — missing or invalid token
403Forbidden — token lacks the required scope
404Not Found — resource does not exist
409Conflict — duplicate resource (e.g. team slug)
429Too Many Requests — rate limit exceeded
500Internal Server Error

Incidents

Create, list, retrieve, and update incidents.

GET/api/v1/incidentsList incidents

Returns all incidents for the company.

Scope:incidents:read

Response 200

Array of incidents

json
{
  "incidents": [
    {
      "id": 1,
      "human_id": "INC-2025-001",
      "service": "payments",
      "regions": [
        "us-east-1"
      ],
      "severity": "sev1",
      "slack_channel_id": "C08ABC123",
      "meet_url": "https://meet.google.com/abc-defg-hij",
      "doc_url": "https://docs.google.com/d/1abc",
      "status": "open",
      "status_changed_at": "2025-01-30T12:05:00Z",
      "issue_type": "incident",
      "impact_summary": "Payment processing delayed for EU customers",
      "impact_started_at": "2025-01-30T11:55:00Z",
      "first_reported_at": "2025-01-30T11:58:00Z",
      "first_responded_at": "2025-01-30T12:00:00Z",
      "recovered_at": null,
      "duration_seconds": 300,
      "duration_anchor": "impact_started_at",
      "team_id": 42,
      "event_count": 3,
      "incident_manager": "[email protected]",
      "last_event_at": "2025-01-30T12:05:00Z",
      "last_event_summary": "Investigating root cause",
      "created_at": "2025-01-30T12:00:00Z",
      "created_by": "[email protected]",
      "custom_fields": {}
    }
  ]
}

Example

bash
curl -X GET \
  'https://{company}.api.tellagen.com/api/v1/incidents' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN'
POST/api/v1/incidentsCreate incident

Creates a new incident. If Slack is configured and create_slack_channel is true, a Slack channel is automatically created.

Scope:incidents:write

Request body

FieldTypeRequiredDescription
servicestringNoService name (max 128 chars)
regionsstring[]NoAffected regions
severitystringNoSeverity key. Values are configurable per company (defaults: sev1–sev4). Uses company default if omitted.
short_titlestringNoShort summary (max 12 chars, auto-slugified). Required if company setting short_title_required is true.
doc_urlstringNoDocument URL (e.g. a runbook or postmortem doc)
team_idintegerNoOwning team ID. Auto-assigned from service if omitted.
create_slack_channelbooleanNoCreate a Slack channel for the incident
invite_usergroupsstring[]NoSlack user group handles to invite
json
{
  "service": "payments",
  "regions": [
    "us-east-1"
  ],
  "severity": "sev2",
  "short_title": "timeout",
  "doc_url": "https://docs.google.com/d/1abc",
  "create_slack_channel": true
}

Response 201

The created incident

json
{
  "incident": {
    "id": 1,
    "human_id": "INC-2025-001",
    "service": "payments",
    "regions": [
      "us-east-1"
    ],
    "severity": "sev2",
    "slack_channel_id": "C08ABC123",
    "meet_url": "",
    "doc_url": "https://docs.google.com/d/1abc",
    "status": "open",
    "status_changed_at": "2025-01-30T12:00:00Z",
    "issue_type": "",
    "impact_summary": "",
    "impact_started_at": null,
    "first_reported_at": null,
    "first_responded_at": null,
    "recovered_at": null,
    "duration_seconds": 0,
    "duration_anchor": "created_at",
    "team_id": 42,
    "event_count": 0,
    "incident_manager": "",
    "last_event_at": null,
    "last_event_summary": "",
    "created_at": "2025-01-30T12:00:00Z",
    "created_by": "[email protected]",
    "custom_fields": {}
  }
}

Example

bash
curl -X POST \
  'https://{company}.api.tellagen.com/api/v1/incidents' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "service": "payments",
  "regions": [
    "us-east-1"
  ],
  "severity": "sev2",
  "short_title": "timeout",
  "doc_url": "https://docs.google.com/d/1abc",
  "create_slack_channel": true
}'
GET/api/v1/incidents/{id}Get incident

Returns a single incident by ID.

Scope:incidents:read

Path parameters

FieldTypeRequiredDescription
idintegerYesIncident ID

Response 200

The incident

json
{
  "incident": {
    "id": 1,
    "human_id": "INC-2025-001",
    "service": "payments",
    "regions": [
      "us-east-1"
    ],
    "severity": "sev2",
    "slack_channel_id": "C08ABC123",
    "meet_url": "https://meet.google.com/abc-defg-hij",
    "doc_url": "https://docs.google.com/d/1abc",
    "status": "active",
    "status_changed_at": "2025-01-30T12:05:00Z",
    "issue_type": "incident",
    "impact_summary": "Payment processing delayed for EU customers",
    "impact_started_at": "2025-01-30T11:55:00Z",
    "first_reported_at": "2025-01-30T11:58:00Z",
    "first_responded_at": "2025-01-30T12:00:00Z",
    "recovered_at": null,
    "duration_seconds": 600,
    "duration_anchor": "impact_started_at",
    "team_id": 42,
    "event_count": 5,
    "incident_manager": "[email protected]",
    "last_event_at": "2025-01-30T12:10:00Z",
    "last_event_summary": "Investigating root cause",
    "created_at": "2025-01-30T12:00:00Z",
    "created_by": "[email protected]",
    "custom_fields": {}
  }
}

Example

bash
curl -X GET \
  'https://{company}.api.tellagen.com/api/v1/incidents/{id}' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN'
PATCH/api/v1/incidents/{id}Update incident

Updates incident fields. Changes are tracked in the changelog.

Scope:incidents:write

Path parameters

FieldTypeRequiredDescription
idintegerYesIncident ID

Request body

FieldTypeRequiredDescription
servicestringNoService name
regionsstring[]NoAffected regions
severitystringNoSeverity key. Values are configurable per company (defaults: sev1–sev4).
slack_channel_idstringNoSlack channel ID
meet_urlstringNoMeeting URL
doc_urlstringNoDocument URL (e.g. a runbook or postmortem doc)
statusstringNoIncident status. Values are configurable per company (defaults: open, active, on-hold, monitoring, resolved, closed).
issue_typestringNoClassification type (e.g. incident, ticket, alert)
impact_summarystringNoSummary of the incident's impact
impact_started_atstring (ISO 8601)NoWhen the impact began
first_reported_atstring (ISO 8601)NoWhen the incident was first reported
first_responded_atstring (ISO 8601)NoWhen the first response occurred
recovered_atstring (ISO 8601)NoWhen the incident was recovered
json
{
  "severity": "sev1",
  "status": "resolved",
  "issue_type": "incident",
  "impact_summary": "Full payment outage in EU region",
  "impact_started_at": "2025-01-30T11:55:00Z",
  "recovered_at": "2025-01-30T13:30:00Z"
}

Response 200

The updated incident

json
{
  "incident": {
    "id": 1,
    "human_id": "INC-2025-001",
    "service": "payments",
    "regions": [
      "us-east-1"
    ],
    "severity": "sev1",
    "slack_channel_id": "C08ABC123",
    "meet_url": "https://meet.google.com/abc-defg-hij",
    "doc_url": "https://docs.google.com/d/1abc",
    "status": "resolved",
    "status_changed_at": "2025-01-30T13:30:00Z",
    "issue_type": "incident",
    "impact_summary": "Full payment outage in EU region",
    "impact_started_at": "2025-01-30T11:55:00Z",
    "first_reported_at": "2025-01-30T11:58:00Z",
    "first_responded_at": "2025-01-30T12:00:00Z",
    "recovered_at": "2025-01-30T13:30:00Z",
    "duration_seconds": 5700,
    "duration_anchor": "impact_started_at",
    "team_id": 42,
    "event_count": 12,
    "incident_manager": "[email protected]",
    "last_event_at": "2025-01-30T13:30:00Z",
    "last_event_summary": "Service fully recovered",
    "created_at": "2025-01-30T12:00:00Z",
    "created_by": "[email protected]",
    "custom_fields": {}
  }
}

Example

bash
curl -X PATCH \
  'https://{company}.api.tellagen.com/api/v1/incidents/{id}' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "severity": "sev1",
  "status": "resolved",
  "issue_type": "incident",
  "impact_summary": "Full payment outage in EU region",
  "impact_started_at": "2025-01-30T11:55:00Z",
  "recovered_at": "2025-01-30T13:30:00Z"
}'
POST/api/v1/incidents/{id}/rename-slack-channelRename Slack channel

Renames the incident's Slack channel based on the company's channel name template.

Scope:incidents:write

Path parameters

FieldTypeRequiredDescription
idintegerYesIncident ID

Response 200

The new channel name

json
{
  "channel_name": "inc-2025-001-payments"
}

Example

bash
curl -X POST \
  'https://{company}.api.tellagen.com/api/v1/incidents/{id}/rename-slack-channel' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN'

Timeline

Record events in the incident timeline.

GET/api/v1/incidents/{id}/timelineList timeline events

Returns all timeline events for the incident, including attachments.

Scope:incidents:read

Path parameters

FieldTypeRequiredDescription
idintegerYesIncident ID

Response 200

Array of timeline events

json
{
  "events": [
    {
      "id": 100,
      "incident_id": 1,
      "at": "2025-01-30T12:10:00Z",
      "is_key": false,
      "source": "manual",
      "source_ref": "",
      "type": "action",
      "icon": "🔧",
      "title": "",
      "body": "Restarted payment service",
      "tags": [],
      "created_by": "[email protected]",
      "comment_count": 0,
      "attachments": []
    }
  ]
}

Example

bash
curl -X GET \
  'https://{company}.api.tellagen.com/api/v1/incidents/{id}/timeline' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN'
POST/api/v1/incidents/{id}/timelineAdd timeline event

Adds a new event to the incident timeline.

Scope:incidents:write

Path parameters

FieldTypeRequiredDescription
idintegerYesIncident ID

Request body

FieldTypeRequiredDescription
bodystringYesEvent description
atstringNoISO 8601 timestamp (defaults to now)
titlestringNoEvent title
sourcestringNoEvent source (e.g. "user", "api")
typestringNoEvent type (e.g. "note", "action")
iconstringNoEmoji icon (max 8 runes)
tagsstring[]NoTags for categorisation
is_keybooleanNoMark as a key event (default false)
json
{
  "body": "Restarted payment service",
  "type": "action",
  "icon": "🔧"
}

Response 201

The created timeline event

json
{
  "event": {
    "id": 100,
    "incident_id": 1,
    "at": "2025-01-30T12:10:00Z",
    "is_key": false,
    "source": "api",
    "source_ref": "",
    "type": "action",
    "icon": "🔧",
    "title": "",
    "body": "Restarted payment service",
    "tags": [],
    "created_by": "[email protected]",
    "comment_count": 0,
    "attachments": []
  }
}

Example

bash
curl -X POST \
  'https://{company}.api.tellagen.com/api/v1/incidents/{id}/timeline' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "body": "Restarted payment service",
  "type": "action",
  "icon": "🔧"
}'
GET/api/v1/timeline/{id}Get timeline event

Returns a single timeline event by ID.

Scope:incidents:read

Path parameters

FieldTypeRequiredDescription
idintegerYesTimeline event ID

Response 200

The timeline event

json
{
  "event": {
    "id": 100,
    "incident_id": 1,
    "at": "2025-01-30T12:10:00Z",
    "is_key": false,
    "source": "manual",
    "source_ref": "",
    "type": "action",
    "icon": "🔧",
    "title": "",
    "body": "Restarted payment service",
    "tags": [],
    "created_by": "[email protected]",
    "comment_count": 0,
    "attachments": []
  }
}

Example

bash
curl -X GET \
  'https://{company}.api.tellagen.com/api/v1/timeline/{id}' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN'
PATCH/api/v1/timeline/{id}Update timeline event

Updates an existing timeline event.

Scope:incidents:write

Path parameters

FieldTypeRequiredDescription
idintegerYesTimeline event ID

Request body

FieldTypeRequiredDescription
bodystringNoEvent description (cannot be empty)
titlestringNoEvent title
iconstringNoEmoji icon (max 8 runes)
typestringNoEvent type
atstringNoISO 8601 timestamp (cannot be in the future)
tagsstring[]NoTags for categorisation
is_keybooleanNoMark as a key event
json
{
  "body": "Restarted payment service — confirmed recovery"
}

Response 200

The updated timeline event

json
{
  "event": {
    "id": 100,
    "incident_id": 1,
    "at": "2025-01-30T12:10:00Z",
    "is_key": false,
    "source": "manual",
    "source_ref": "",
    "type": "action",
    "icon": "🔧",
    "title": "",
    "body": "Restarted payment service — confirmed recovery",
    "tags": [],
    "created_by": "[email protected]",
    "comment_count": 0,
    "attachments": []
  }
}

Example

bash
curl -X PATCH \
  'https://{company}.api.tellagen.com/api/v1/timeline/{id}' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "body": "Restarted payment service — confirmed recovery"
}'
DELETE/api/v1/timeline/{id}Delete timeline event

Deletes a timeline event and its attachments.

Scope:incidents:write

Path parameters

FieldTypeRequiredDescription
idintegerYesTimeline event ID

Returns 204 with no body.

Example

bash
curl -X DELETE \
  'https://{company}.api.tellagen.com/api/v1/timeline/{id}' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN'

Services

Manage the service catalogue.

GET/api/v1/servicesList services

Returns all services, optionally including archived ones.

Scope:services:read

Query parameters

FieldTypeRequiredDescription
include_archivedbooleanNoInclude archived services (default false)

Response 200

Array of services

json
{
  "services": [
    {
      "id": 5,
      "name": "Payment Service",
      "slug": "payment-service",
      "description": "Handles all payment processing",
      "owner_team_id": 42,
      "owner_team_name": "Platform Team",
      "owner_team_slug": "platform-team",
      "tier": "t0",
      "tags": [
        "critical",
        "payments"
      ],
      "external_id": "",
      "created_at": "2025-01-15T10:00:00Z",
      "updated_at": "2025-01-15T10:00:00Z",
      "archived_at": null
    }
  ]
}

Example

bash
curl -X GET \
  'https://{company}.api.tellagen.com/api/v1/services' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN'
POST/api/v1/servicesCreate service

Adds a new service. Slug is auto-generated from name if omitted.

Scope:services:write

Request body

FieldTypeRequiredDescription
namestringYesService name (1-128 chars)
slugstringNoURL-safe slug (auto-generated if omitted)
descriptionstringNoService description
owner_team_idintegerNoOwning team ID
tierstringNot0 | t1 | t2 (default) | t3
tagsstring[]NoTags for categorisation
external_idstringNoExternal system identifier
json
{
  "name": "Payment Service",
  "description": "Handles all payment processing",
  "owner_team_id": 42,
  "tier": "t0",
  "tags": [
    "critical",
    "payments"
  ]
}

Response 201

The created service

json
{
  "service": {
    "id": 5,
    "name": "Payment Service",
    "slug": "payment-service",
    "description": "Handles all payment processing",
    "owner_team_id": 42,
    "tier": "t0",
    "tags": [
      "critical",
      "payments"
    ],
    "external_id": "",
    "created_at": "2025-01-30T12:00:00Z",
    "updated_at": "2025-01-30T12:00:00Z",
    "archived_at": null
  }
}

Example

bash
curl -X POST \
  'https://{company}.api.tellagen.com/api/v1/services' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Payment Service",
  "description": "Handles all payment processing",
  "owner_team_id": 42,
  "tier": "t0",
  "tags": [
    "critical",
    "payments"
  ]
}'
GET/api/v1/services/{id}Get service

Returns a single service by ID.

Scope:services:read

Path parameters

FieldTypeRequiredDescription
idintegerYesService ID

Response 200

The service

json
{
  "service": {
    "id": 5,
    "name": "Payment Service",
    "slug": "payment-service",
    "description": "Handles all payment processing",
    "owner_team_id": 42,
    "owner_team_name": "Platform Team",
    "owner_team_slug": "platform-team",
    "tier": "t0",
    "tags": [
      "critical",
      "payments"
    ],
    "external_id": "",
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-01-15T10:00:00Z",
    "archived_at": null
  }
}

Example

bash
curl -X GET \
  'https://{company}.api.tellagen.com/api/v1/services/{id}' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN'
PATCH/api/v1/services/{id}Update service

Updates service fields.

Scope:services:write

Path parameters

FieldTypeRequiredDescription
idintegerYesService ID

Request body

FieldTypeRequiredDescription
namestringNoService name (1-128 chars)
descriptionstringNoService description
owner_team_idintegerNoOwning team ID
tierstringNot0 | t1 | t2 | t3
tagsstring[]NoTags
external_idstringNoExternal system identifier
json
{
  "tier": "t1",
  "tags": [
    "payments",
    "core"
  ]
}

Response 200

The updated service

json
{
  "service": {
    "id": 5,
    "name": "Payment Service",
    "slug": "payment-service",
    "tier": "t1",
    "tags": [
      "payments",
      "core"
    ],
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-01-30T12:00:00Z",
    "archived_at": null
  }
}

Example

bash
curl -X PATCH \
  'https://{company}.api.tellagen.com/api/v1/services/{id}' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "tier": "t1",
  "tags": [
    "payments",
    "core"
  ]
}'
DELETE/api/v1/services/{id}Archive service

Soft-deletes (archives) a service. It can still be retrieved with include_archived=true.

Scope:services:write

Path parameters

FieldTypeRequiredDescription
idintegerYesService ID

Returns 204 with no body.

Example

bash
curl -X DELETE \
  'https://{company}.api.tellagen.com/api/v1/services/{id}' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN'

Teams

Manage teams and their members.

GET/api/v1/teamsList teams

Returns all teams, optionally including archived ones.

Scope:teams:read

Query parameters

FieldTypeRequiredDescription
include_archivedbooleanNoInclude archived teams (default false)

Response 200

Array of teams

json
{
  "teams": [
    {
      "id": 42,
      "name": "Platform Team",
      "slug": "platform-team",
      "description": "Core platform infrastructure",
      "parent_team_id": null,
      "member_count": 12,
      "created_at": "2025-01-10T09:00:00Z",
      "updated_at": "2025-01-10T09:00:00Z",
      "archived_at": null
    }
  ]
}

Example

bash
curl -X GET \
  'https://{company}.api.tellagen.com/api/v1/teams' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN'
POST/api/v1/teamsCreate team

Creates a new team. Slug is auto-generated from name if omitted. Returns 409 if slug already exists.

Scope:teams:write

Request body

FieldTypeRequiredDescription
namestringYesTeam name (1-128 chars)
slugstringNoURL-safe slug (auto-generated if omitted)
descriptionstringNoTeam description
parent_team_idintegerNoParent team ID for hierarchy
json
{
  "name": "Platform Team",
  "description": "Core platform infrastructure"
}

Response 201

The created team

json
{
  "team": {
    "id": 42,
    "name": "Platform Team",
    "slug": "platform-team",
    "description": "Core platform infrastructure",
    "parent_team_id": null,
    "member_count": 0,
    "created_at": "2025-01-30T12:00:00Z",
    "updated_at": "2025-01-30T12:00:00Z",
    "archived_at": null
  }
}

Example

bash
curl -X POST \
  'https://{company}.api.tellagen.com/api/v1/teams' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Platform Team",
  "description": "Core platform infrastructure"
}'
GET/api/v1/teams/{id}Get team

Returns a single team by ID.

Scope:teams:read

Path parameters

FieldTypeRequiredDescription
idintegerYesTeam ID

Response 200

The team

json
{
  "team": {
    "id": 42,
    "name": "Platform Team",
    "slug": "platform-team",
    "description": "Core platform infrastructure",
    "parent_team_id": null,
    "member_count": 12,
    "created_at": "2025-01-10T09:00:00Z",
    "updated_at": "2025-01-10T09:00:00Z",
    "archived_at": null
  }
}

Example

bash
curl -X GET \
  'https://{company}.api.tellagen.com/api/v1/teams/{id}' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN'
PATCH/api/v1/teams/{id}Update team

Updates team fields. Prevents circular parent references.

Scope:teams:write

Path parameters

FieldTypeRequiredDescription
idintegerYesTeam ID

Request body

FieldTypeRequiredDescription
namestringNoTeam name (1-128 chars)
descriptionstringNoTeam description
parent_team_idintegerNoParent team ID
json
{
  "description": "Core platform and infrastructure"
}

Response 200

The updated team

json
{
  "team": {
    "id": 42,
    "name": "Platform Team",
    "slug": "platform-team",
    "description": "Core platform and infrastructure",
    "parent_team_id": null,
    "member_count": 12,
    "created_at": "2025-01-10T09:00:00Z",
    "updated_at": "2025-01-30T12:00:00Z",
    "archived_at": null
  }
}

Example

bash
curl -X PATCH \
  'https://{company}.api.tellagen.com/api/v1/teams/{id}' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "Core platform and infrastructure"
}'
DELETE/api/v1/teams/{id}Archive team

Soft-deletes (archives) a team.

Scope:teams:write

Path parameters

FieldTypeRequiredDescription
idintegerYesTeam ID

Returns 204 with no body.

Example

bash
curl -X DELETE \
  'https://{company}.api.tellagen.com/api/v1/teams/{id}' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN'
GET/api/v1/teams/{id}/membersList team members

Returns all members of the team with their user details.

Scope:teams:read

Path parameters

FieldTypeRequiredDescription
idintegerYesTeam ID

Response 200

Array of team members

json
{
  "members": [
    {
      "team_id": 42,
      "user_id": 100,
      "role": "lead",
      "email": "[email protected]",
      "display_name": "Jane Doe",
      "avatar_url": ""
    }
  ]
}

Example

bash
curl -X GET \
  'https://{company}.api.tellagen.com/api/v1/teams/{id}/members' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN'
POST/api/v1/teams/{id}/membersAdd team member

Adds a user to the team.

Scope:teams:write

Path parameters

FieldTypeRequiredDescription
idintegerYesTeam ID

Request body

FieldTypeRequiredDescription
user_idintegerYesUser ID to add
rolestringNomember (default) | lead
json
{
  "user_id": 100,
  "role": "lead"
}

Response 201

The created team member

json
{
  "member": {
    "team_id": 42,
    "user_id": 100,
    "role": "lead",
    "created_at": "2025-01-30T12:00:00Z"
  }
}

Example

bash
curl -X POST \
  'https://{company}.api.tellagen.com/api/v1/teams/{id}/members' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "user_id": 100,
  "role": "lead"
}'
PATCH/api/v1/teams/{id}/members/{userId}Update team member

Updates a team member's role.

Scope:teams:write

Path parameters

FieldTypeRequiredDescription
idintegerYesTeam ID
userIdintegerYesUser ID

Request body

FieldTypeRequiredDescription
rolestringYesmember | lead
json
{
  "role": "member"
}

Response 200

The updated team member

json
{
  "member": {
    "team_id": 42,
    "user_id": 100,
    "role": "member",
    "created_at": "2025-01-10T09:00:00Z"
  }
}

Example

bash
curl -X PATCH \
  'https://{company}.api.tellagen.com/api/v1/teams/{id}/members/{userId}' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "role": "member"
}'
DELETE/api/v1/teams/{id}/members/{userId}Remove team member

Removes a user from the team.

Scope:teams:write

Path parameters

FieldTypeRequiredDescription
idintegerYesTeam ID
userIdintegerYesUser ID

Returns 204 with no body.

Example

bash
curl -X DELETE \
  'https://{company}.api.tellagen.com/api/v1/teams/{id}/members/{userId}' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN'

Custom Fields

Define custom fields and set their values on incidents.

GET/api/v1/custom-fieldsList custom fields

Returns all custom field definitions, optionally including archived ones.

Scope:custom_fields:read

Query parameters

FieldTypeRequiredDescription
include_archivedbooleanNoInclude archived fields (default false)

Response 200

Array of custom fields

json
{
  "fields": [
    {
      "id": 50,
      "name": "Affected Users",
      "slug": "affected_users",
      "field_type": "number",
      "description": "Number of users impacted",
      "default_value": 0,
      "config": {
        "min": 0,
        "precision": 0
      },
      "required": false,
      "sort_order": 1,
      "category": "impact",
      "visibility_level": "prominent",
      "show_on_creation": true,
      "required_on_creation": false,
      "auto_add_to_layout": true,
      "external_source": "",
      "archived_at": null,
      "created_at": "2025-01-10T09:00:00Z",
      "updated_at": "2025-01-10T09:00:00Z"
    }
  ]
}

Example

bash
curl -X GET \
  'https://{company}.api.tellagen.com/api/v1/custom-fields' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN'
POST/api/v1/custom-fieldsCreate custom field

Defines a new custom field. Slug is auto-generated from name if omitted.

Scope:custom_fields:write

Request body

FieldTypeRequiredDescription
namestringYesField name (1-64 chars)
slugstringNoURL-safe slug (auto-generated if omitted)
field_typestringYesstring | number | boolean | date | time | datetime | monetary | json | select | multi_select
descriptionstringNoField description
default_valueanyNoDefault value
configobjectNoType-specific config (e.g. min/max for number, options for select)
requiredbooleanNoWhether the field is required
categorystringNocontext | impact | analysis | external | custom
visibility_levelstringNoalways | prominent | standard | collapsed
show_on_creationbooleanNoShow on incident creation form
required_on_creationbooleanNoRequired on incident creation form
auto_add_to_layoutbooleanNoAuto-add to incident workspace layout
external_sourcestringNoExternal source identifier (for external category)
json
{
  "name": "Affected Users",
  "field_type": "number",
  "description": "Number of users impacted",
  "category": "impact",
  "visibility_level": "prominent",
  "show_on_creation": true,
  "config": {
    "min": 0,
    "precision": 0
  }
}

Response 201

The created custom field

json
{
  "field": {
    "id": 50,
    "name": "Affected Users",
    "slug": "affected_users",
    "field_type": "number",
    "description": "Number of users impacted",
    "default_value": null,
    "config": {
      "min": 0,
      "precision": 0
    },
    "required": false,
    "sort_order": 0,
    "category": "impact",
    "visibility_level": "prominent",
    "show_on_creation": true,
    "required_on_creation": false,
    "auto_add_to_layout": false,
    "external_source": "",
    "archived_at": null,
    "created_at": "2025-01-30T12:00:00Z",
    "updated_at": "2025-01-30T12:00:00Z"
  }
}

Example

bash
curl -X POST \
  'https://{company}.api.tellagen.com/api/v1/custom-fields' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Affected Users",
  "field_type": "number",
  "description": "Number of users impacted",
  "category": "impact",
  "visibility_level": "prominent",
  "show_on_creation": true,
  "config": {
    "min": 0,
    "precision": 0
  }
}'
GET/api/v1/custom-fields/{id}Get custom field

Returns a single custom field definition by ID.

Scope:custom_fields:read

Path parameters

FieldTypeRequiredDescription
idintegerYesCustom field ID

Response 200

The custom field

json
{
  "field": {
    "id": 50,
    "name": "Affected Users",
    "slug": "affected_users",
    "field_type": "number",
    "description": "Number of users impacted",
    "default_value": 0,
    "config": {
      "min": 0,
      "precision": 0
    },
    "required": false,
    "sort_order": 1,
    "category": "impact",
    "visibility_level": "prominent",
    "show_on_creation": true,
    "required_on_creation": false,
    "auto_add_to_layout": true,
    "external_source": "",
    "archived_at": null,
    "created_at": "2025-01-10T09:00:00Z",
    "updated_at": "2025-01-10T09:00:00Z"
  }
}

Example

bash
curl -X GET \
  'https://{company}.api.tellagen.com/api/v1/custom-fields/{id}' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN'
PATCH/api/v1/custom-fields/{id}Update custom field

Updates a custom field definition.

Scope:custom_fields:write

Path parameters

FieldTypeRequiredDescription
idintegerYesCustom field ID

Request body

FieldTypeRequiredDescription
namestringNoField name (1-64 chars)
descriptionstringNoField description
default_valueanyNoDefault value
configobjectNoType-specific config
requiredbooleanNoWhether the field is required
sort_orderintegerNoDisplay order
categorystringNocontext | impact | analysis | external | custom
visibility_levelstringNoalways | prominent | standard | collapsed
show_on_creationbooleanNoShow on incident creation form
required_on_creationbooleanNoRequired on incident creation form
auto_add_to_layoutbooleanNoAuto-add to layout
external_sourcestringNoExternal source identifier
json
{
  "required": true,
  "sort_order": 2
}

Response 200

The updated custom field

json
{
  "field": {
    "id": 50,
    "name": "Affected Users",
    "slug": "affected_users",
    "field_type": "number",
    "required": true,
    "sort_order": 2,
    "created_at": "2025-01-10T09:00:00Z",
    "updated_at": "2025-01-30T12:00:00Z"
  }
}

Example

bash
curl -X PATCH \
  'https://{company}.api.tellagen.com/api/v1/custom-fields/{id}' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "required": true,
  "sort_order": 2
}'
DELETE/api/v1/custom-fields/{id}Archive custom field

Soft-deletes (archives) a custom field.

Scope:custom_fields:write

Path parameters

FieldTypeRequiredDescription
idintegerYesCustom field ID

Returns 204 with no body.

Example

bash
curl -X DELETE \
  'https://{company}.api.tellagen.com/api/v1/custom-fields/{id}' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN'
GET/api/v1/incidents/{id}/custom-fieldsGet incident field values

Returns all custom field values set on the incident.

Scope:custom_fields:read

Path parameters

FieldTypeRequiredDescription
idintegerYesIncident ID

Response 200

Array of custom field values

json
{
  "values": [
    {
      "id": 1,
      "incident_id": 1,
      "custom_field_id": 50,
      "value": 1500,
      "created_at": "2025-01-30T12:05:00Z",
      "updated_at": "2025-01-30T12:05:00Z"
    }
  ]
}

Example

bash
curl -X GET \
  'https://{company}.api.tellagen.com/api/v1/incidents/{id}/custom-fields' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN'
PUT/api/v1/incidents/{id}/custom-fieldsSet incident field values

Sets or updates custom field values on the incident.

Scope:custom_fields:write

Path parameters

FieldTypeRequiredDescription
idintegerYesIncident ID

Request body

FieldTypeRequiredDescription
valuesarrayYesArray of { field_id, value } objects
json
{
  "values": [
    {
      "field_id": 50,
      "value": 1500
    },
    {
      "field_id": 51,
      "value": "enterprise"
    }
  ]
}

Response 200

The updated custom field values

json
{
  "values": [
    {
      "id": 1,
      "incident_id": 1,
      "custom_field_id": 50,
      "value": 1500,
      "created_at": "2025-01-30T12:05:00Z",
      "updated_at": "2025-01-30T12:10:00Z"
    },
    {
      "id": 2,
      "incident_id": 1,
      "custom_field_id": 51,
      "value": "enterprise",
      "created_at": "2025-01-30T12:10:00Z",
      "updated_at": "2025-01-30T12:10:00Z"
    }
  ]
}

Example

bash
curl -X PUT \
  'https://{company}.api.tellagen.com/api/v1/incidents/{id}/custom-fields' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "values": [
    {
      "field_id": 50,
      "value": 1500
    },
    {
      "field_id": 51,
      "value": "enterprise"
    }
  ]
}'