The meta.sr.ht API allows you to view and edit user information on meta.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 meta.sr.ht:

• audit:read: read the security audit log
• keys:read, keys:write: read & update user SSH & PGP keys
• profile:read, profile:write: read & update profile information

#Resources

#User resource

meta.sr.ht expands on the standard user resource.

{
  "canonical_name": "~username",
  "name": "username",
  "email": "email",
  "url": "url" or null,
  "location": "location" or null,
  "bio": "bio" or null,
  "use_pgp_key": pgp key resource ID
}

• use_pgp_key is the ID of the user's preferred PGP key, which can be found via GET /api/user/pgp-keys/:id.

#Audit log entry resource

{
  "id": integer,
  "ip": "IP address",
  "action": "event type",
  "details": "event details",
  "created": "timestamp"
}

#SSH key resource

{
  "id": integer,
  "authorized": "timestamp",
  "comment": "SSH key comment",
  "fingerprint": "SSH key fingerprint",
  "key": "SSH key (authorized_keys format)",
  "owner": short-form user resource,
  "last_used": "timestamp"
}

• last_used is omitted when viewing an SSH key which is not owned by the authorized user.

#PGP key resource

{
  "id": integer,
  "key": "armored PGP key",
  "key_id": "PGP key fingerprint",
  "email": "First email found in the PGP key",
  "authorized": "timestamp",
  "owner": short-form user resource
}

#Endpoints

#GET /api/user/profile

Returns the authenticated user's user resource.

OAuth scope: profile:read

#PUT /api/user/profile

Updates the authenticated user's profile.

OAuth scope: profile:write

Request body

{
  "url": "url" or null, (optional)
  "location": "location" or null, (optional)
  "bio": "bio" or null, (optional)
  "email": "email" (optional)
}

Response

Updated user resource.

Notes

• When updating email, the returned user resource will not reflect the update. The user must click the confirmation link which is sent to their new email address before the update will take effect.

#GET /api/user/audit-log

List of audit log entry resources.

OAuth scope: audit-log:read

#GET /api/user/ssh-keys

List of SSH key resources.

OAuth scope: keys:read

#POST /api/user/ssh-keys

Creates a new SSH key resource.

OAuth scope: keys:write

Request body

{
  "ssh-key": "SSH key (authorized_keys format)"
}

Response

The new SSH key resource.

#GET /api/user/ssh-keys/:id

Retrieves an SSH key resource.

OAuth scope: keys:read

#PUT /api/user/ssh-keys/:id

Updates the "last_used" time of this SSH key resource.

OAuth scope: keys:read

Response

The updated SSH key resource.

#DELETE /api/user/ssh-keys/:id

Deletes this SSH key resource.

OAuth scope: keys:write

#GET /api/user/pgp-keys

List of PGP key resources.

OAuth scope: keys:read

#POST /api/user/pgp-keys

Creates a new PGP key resource.

OAuth scope: keys:write

Request body

{
  "pgp-key": "armored PGP key"
}

Response

The new PGP key resource.

#GET /api/user/pgp-keys/:id

Retrieves a PGP key resource.

OAuth scope: keys:read

#DELETE /api/user/pgp-keys/:id

Deletes this PGP key resource.

OAuth scope: keys:write

#Webhooks

#/api/user/...

Webhook for user events. Includes the standard webhook endpoints

#profile:update

Issued when the user's profile (bio, email, etc) is updated.

OAuth scope: profile:read

Request body

The updated user resource.

#ssh-key:add

Issued when the user adds an SSH key to their account.

OAuth scope: keys:read

Request body

The new SSH key resource.

#ssh-key:remove

Issued when the user removes an SSH key from their account.

OAuth scope: keys:read

Request body

{
  "id": integer ID of the affected SSH key resource
}

#pgp-key:add

Issued when the user adds a PGP key to their account.

OAuth scope: keys:read

Request body

The new PGP key resource.

#pgp-key:remove

Issued when the user removes a PGP key from their account.

OAuth scope: keys:read

Request body

{
  "id": integer ID of the affected PGP key resource
}