---
title: meta.sr.ht API reference
---
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](/api-conventions.md).
## Authentication
Authentication is done via the [meta.sr.ht OAuth
flow](../oauth-api.md). 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](/api-conventions.md#user-resource).
```json
{
"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`](#get-apiuserpgp-keysid).
### Audit log entry resource
```json
{
"id": integer,
"ip": "IP address",
"action": "event type",
"details": "event details",
"created": "timestamp"
}
```
### SSH key resource
```json
{
"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
```json
{
"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](#user-resource).
**OAuth scope**: `profile:read`
### PUT /api/user/profile
Updates the authenticated user's profile.
**OAuth scope**: `profile:write`
**Request body**
```json
{
"url": "url" or null, (optional)
"location": "location" or null, (optional)
"bio": "bio" or null, (optional)
"email": "email" (optional)
}
```
**Response**
Updated [user resource](#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](#audit-log-entry-resource).
**OAuth scope**: `audit-log:read`
### GET /api/user/ssh-keys
List of [SSH key resources](#ssh-key-resource).
**OAuth scope**: `keys:read`
### POST /api/user/ssh-keys
Creates a new [SSH key resource](#ssh-key-resource).
**OAuth scope**: `keys:write`
**Request body**
```json
{
"ssh-key": "SSH key (authorized_keys format)"
}
```
**Response**
The new [SSH key resource](#ssh-key-resource).
### GET /api/user/ssh-keys/:id
Retrieves an [SSH key resource](#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](#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](#pgp-key-resource).
**OAuth scope**: `keys:read`
### POST /api/user/pgp-keys
Creates a new [PGP key resource](#pgp-key-resource).
**OAuth scope**: `keys:write`
**Request body**
```json
{
"pgp-key": "armored PGP key"
}
```
**Response**
The new [PGP key resource](#pgp-key-resource).
### GET /api/user/pgp-keys/:id
Retrieves a [PGP key resource](#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](/api-conventions.md#webhooks)
#### profile:update
Issued when the user's profile (bio, email, etc) is updated.
**OAuth scope**: `profile:read`
**Request body**
The updated [user resource](#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-resource).
#### ssh-key:remove
Issued when the user removes an SSH key from their account.
**OAuth scope**: `keys:read`
**Request body**
```json
{
"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-resource).
#### pgp-key:remove
Issued when the user removes a PGP key from their account.
**OAuth scope**: `keys:read`
**Request body**
```json
{
"id": integer ID of the affected PGP key resource
}
```
