sr.ht-docs/todo.sr.ht/api.md

title
todo.sr.ht API reference

NOTICE: This is the documentation for the legacy REST API. It is being replaced with the GraphQL API.

The todo.sr.ht API allows you to browse, create, and manage repositories on todo.sr.ht programmatically. This API follows the standard sourcehut API conventions.

Authentication

Authentication is done via the meta.sr.ht OAuth flow. The following OAuth scopes are available for todo.sr.ht:

• events:read: read ticket events
• trackers:read, trackers:write: read & write tracker details
• tickets:read, tickets:write: read & write tickets & comments

Resources

Comment resource

{
  "id": integer,
  "created": "timestamp",
  "submitter": { short-form user resource },
  "text": "string (markdown)",
  "ticket" { short-form ticket resoruce }
}

Short form:

{
  "id": integer,
  "created": "timestamp",
  "submitter": { short-form user resource },
  "text": "string (markdown)"
}

Event resource

{
  "id": integer,
  "created": "timestamp",
  "event_type": [ ...list of event types... ],
  "old_status": status or null,
  "old_resolution": resolution or null,
  "new_status": status or null,
  "new_resolution": resolution or null,
  "user": { short-form user resource } or null,
  "ticket": { short-form ticket resource } or null,
  "comment": { short-form comment resource } or null,
  "label": [ ...list of strings... ] or null,
  "by_user": { short-form user resource } or null,
  "from_ticket": { short-form ticket resource } or null
}

Event type may be one or more of created, comment, status_change, label_added, label_removed, assigned_user, unassigned_user, user_mentioned, or ticket_mentioned.

Status fields may be one of reported, confirmed, in_progress, pending, or resolved.

Resolution fields may be one of unresolved, fixed, implemented, wont_fix, by_design, invalid, duplicate, or not_our_bug.

The by_user and from_ticket features are used for events where a ticket or user was mentioned in a comment somewhere. The ticket field and user field are set to the mentioned ticket or user, and the by_user or from_ticket field are set according to the discussion where the mention occured.

Label resource

{
  "name": "string",
  "created": "timestamp",
  "colors": {
    "background": "#rrggbb",
    "text": "#rrggbb"
  },
  "tracker": { short-form tracker resource }
}

Short form:

{
  "name": "string",
  "colors": {
    "background": "#rrggbb",
    "text": "#rrggbb"
  }
}

Ticket resource

{
  "id": integer,
  "ref": "string",
  "tracker": { short-form tracker resource },
  "title": "ticket subject",
  "created": "timestamp",
  "updated": "timestamp",
  "submitter": { short-form user resource },
  "description": "string (markdown)",
  "status": status,
  "resolution": resolution,
  "permissions": {
    "anonymous": [ ...list of strings... ] or null,
    "submitter": [ ...list of strings... ] or null,
    "user": [ ...list of strings... ] or null,
  },
  "labels": [ ...list of label names... ],
  "assignees": [ ...list of short-form user resources... ]
}

Status fields may be one of reported, confirmed, in_progress, pending, or resolved.

Resolution fields may be one of unresolved, fixed, implemented, wont_fix, by_design, invalid, duplicate, or not_our_bug.

Permissions may be one or more of browse, submit, comment, edit, and triage. If null, the permissions are inherited from the tracker.

Short form:

{
  "id": integer,
  "ref": "string",
  "tracker": { short-form tracker resource }
}

Tracker resource

{
  "owner": { short-form user resource },
  "created": "timestamp",
  "updated": "timestamp",
  "name": "string",
  "description": "string (markdown)",
  "default_permissions": {
    "anonymous": [ ...list of permissions... ],
    "submitter": [ ...list of permissions... ],
    "user": [ ...list of permissions... ]
  }
}

Permissions may be one or more of browse, submit, comment, edit, and triage.

Short form:

{
  "owner": { short-form user resource },
  "created": "timestamp",
  "updated": "timestamp",
  "name": "string",
}

Endpoints

Note: usernames are prefixed with ~.

GET /api/user/:username

Retrieves a user resource.

GET /api/user

Equivalent to /api/user/:username, implies the authenticated user.

GET /api/user/:username/trackers

List of tracker resources owned by this user.

OAuth scope: trackers:read

GET /api/trackers

Equivalent to /api/user/:username/trackers, implies the authenticated user.

OAuth scope: trackers:read

POST /api/trackers

Creates a new tracker resource.

OAuth scope: trackers:write

Request body

{
  "name": "tracker name",
  "description": "tracker description (markdown)" (optional)
}

Response

The new tracker resource

GET /api/user/:username/trackers/:tracker-name

Retrieves a tracker resource.

OAuth scope: trackers:read

GET /api/trackers/:tracker-name

Equivalent to /api/user/:username/trackers/:tracker-name, implies the authenticated user.

OAuth scope: trackers:read

PUT /api/user/:username/trackers/:tracker-name

Updates a tracker resource.

{
  "description": "tracker description (markdown)" (optional)
}

OAuth scope: trackers:write

PUT /api/trackers/:tracker-name

Equivalent to /api/user/:username/trackers/:tracker-name, implies the authenticated user.

OAuth scope: trackers:write

DELETE /api/user/:username/trackers/:tracker-name

Deletes a tracker resource.

OAuth scope: trackers:write

DELETE /api/trackers/:tracker-name

Equivalent to /api/user/:username/trackers/:tracker-name, implies the authenticated user.

OAuth scope: trackers:write

GET /api/user/:username/trackers/:tracker-name/labels

List of label resources associated with this tracker.

OAuth scope: trackers:read

GET /api/trackers/:tracker-name/labels

Equivalent to /api/:username/trackers/:tracker-name/labels, implies the authenticated user.

OAuth scope: trackers:read

GET /api/user/:username/trackers/:tracker-name/tickets

List of ticket resources associated with this tracker.

OAuth scope: tickets:read

GET /api/trackers/:tracker-name/tickets

Equivalent to /api/user/:username/trackers/:tracker-name/tickets, implies the authenticated user.

OAuth scope: tickets:read

POST /api/user/:username/trackers/:tracker-name/tickets

Creates a new ticket resources associated with this tracker.

OAuth scope: tickets:write

Request body

{
  "title": "ticket title",
  "description": "ticket description (markdown)" (optional)
}

Response

The new ticket resource

POST /api/trackers/:tracker-name/tickets

Equivalent to /api/user/:username/trackers/:tracker-name/tickets, implies the authenticated user.

OAuth scope: tickets:write

GET /api/user/:username/trackers/:tracker-name/tickets/:ticket-id

Retrieves a ticket resource.

OAuth scope: tickets:read

GET /api/trackers/:tracker-name/tickets/:ticket-id

Equivalent to /api/user/:username/trackers/:tracker-name/tickets/:ticket-id, implies the authenticated user.

OAuth scope: tickets:read

PUT /api/user/:username/trackers/:tracker-name/tickets/:ticket-id

Updates a ticket resource. This endpoint is used to:

• Open or close tickets
• Comment on tickets
• Add or remove labels

OAuth scope: tickets:write

Request body

{
  "comment": "comment text (markdown)" (optional),
  "status": "ticket status enum" (optional),
  "resolution": "ticket resolution enum" (optional),
  "labels": ["list of desired label names"] (optional)
}

Ticket status enum

One of:

• reported
• confirmed
• in_progress
• pending
• resolved

Ticket resolution enum

One of:

• unresolved
• fixed
• implemented
• wont_fix
• by_design
• invalid
• duplicate
• not_our_bug

Response

{
  "ticket": { affected ticket resource },
  "events": [
    list of event resources created by this update
  ]
}

PUT /api/trackers/:tracker-name/tickets/:ticket-id

Equivalent to /api/user/:username/trackers/:tracker-name/tickets/:ticket-id, implies the authenticated user.

OAuth scope: tickets:write

GET /api/user/:username/trackers/:tracker-name/tickets/:ticket-id/events

List of event resources associated with this ticket.

OAuth scope: tickets:read

GET /api/trackers/:tracker-name/tickets/:ticket-id/events

Equivalent to /api/user/:username/trackers/:tracker-name/tickets/:ticket-id/events, implies the authenticated user.

OAuth scope: tickets:read

PUT /api/user/:username/trackers/:tracker-name/tickets/:ticket-id/comments/:comment-id

Edits a comment. Note that the comment ID is required, not the event ID.

Request body

{
  "text": "new comment text (markdown)"
}

OAuth scope: tickets:write

PUT /api/trackers/:tracker-name/tickets/:ticket-id/comments/:comment-id

Equivalent to /api/user/:username/trackers/:tracker-name/tickets/:ticket-id/comments/:comment-id, implies the authenticated user.

OAuth scope: tickets:write

Webhooks

/api/user/...

Webhook for user events. Includes the standard webhook endpoints

tracker:create

Issued when the user creates a new tracker.

OAuth scope: trackers:read

Request body

The new tracker resource.

tracker:update

Issued when the user updates a tracker.

OAuth scope: trackers:read

Request body

The affected tracker resource.

tracker:delete

Issued when the user deletes a tracker.

OAuth scope: trackers:read

Request body

{
  "id": the affected tracker ID
}

ticket:create

Issued when the user creates a new ticket.

OAuth scope: tickets:read

Request body

The new ticket resource.

event:create

Issued when a new event is created for a ticket on this tracker.

OAuth scope: tickets:read

Request body

The new event resource.

/api/user/:username/trackers/:tracker-name

Webhook for tracker events. Includes the standard webhook endpoints

label:create

Issued when a new label is added to this tracker.

OAuth scope: trackers:read

Request body

The new label resource.

label:delete

Issued when a label is removed from this tracker.

OAuth scope: trackers:read

Request body

{
  "id": affected label ID
}

ticket:create

Issued when a ticket is created for this tracker.

OAuth scope: tickets:read

Request body

The new ticket resource.

/api/user/:username/trackers/:tracker-name/tickets/:ticket-id

Webhook for ticket events. Includes the standard webhook endpoints

ticket:update

Issued when this tickets details are updated.

OAuth scope: tickets:read

Request body

The updated ticket resource.

event:create

Issued when a new event is created for this this ticket.

OAuth scope: tickets:read

Request body

The new event resource.