API reference
Projects
Group keys under a monthly budget, and read usage by project.
GET/v1/projects
The account's projects, or a team's with org. Live ones by default, newest first.
Auth: Session, not an API key: Authorization: Bearer <session token>. See Sign in.
| Name | Type | Required | Description |
|---|---|---|---|
org | string | No | Query. A team the account is a member of: its projects. |
state | string | No | Query. active (default), archived or all. |
limit | integer | No | Query. How many projects to return. |
before | string | No | Query. The page.next_before of the previous page. |
GET /v1/projects
curl https://api.usdf.fi/v1/projects \
-H "Authorization: Bearer $SESSION"Response, trimmed
{
"object": "list",
"role": "owner",
"can_manage": true,
"live": …,
"max_live": …,
"data": [{ "object": "project", "id": "prj_…", "name": "research", "budget": { … }, "key_count": …, "archived": false, … }],
"page": { "limit": …, "more": false, "next_before": null }
}POST/v1/projects
The account's own, or a team's with org (by its owner or an admin).
Auth: Session, not an API key: Authorization: Bearer <session token>. See Sign in.
| Name | Type | Required | Description |
|---|---|---|---|
org | string | No | Query. A team the account is a member of. |
name | string | Yes | The project's name. |
budget_ | string or integer or null | No | A monthly budget in USDF base units. Leave it out, or null, for none. |
POST /v1/projects
curl -X POST https://api.usdf.fi/v1/projects \ -H "Authorization: Bearer $SESSION" \ -H "Content-Type: application/json" \ -d '{"name": "research", "budget_units": "20000000"}'
Response, trimmed
{
"object": "project",
"id": "prj_…",
"name": "research",
"budget": { "limit": { "units": "<units>", "usd": "<usd>", "usdf": "<usdf>" }, "spent": { … }, "held": { … }, "left": { … }, "month": "<YYYY-MM>", "resets_at": "<time>" },
"spent_this_month": { … },
"key_count": …,
"archived": false,
"links": { "self": "…", "archive": "…", "usage": "…", "activity": "…" },
…
}GET/v1/projects/{id}
Its budget and what is left of it, what its requests did this UTC month, and its live keys.
Auth: Session, not an API key: Authorization: Bearer <session token>. See Sign in.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Path. The project's id. |
GET /v1/projects/{id}
curl https://api.usdf.fi/v1/projects/{id} \
-H "Authorization: Bearer $SESSION"PATCH/v1/projects/{id}
Its name or monthly budget, by the account or a team's owner or admin. An archived project is not changed.
Auth: Session, not an API key: Authorization: Bearer <session token>. See Sign in.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Path. The project's id. |
name | string | No | The project's name. |
budget_ | string or integer or null | No | A monthly budget in USDF base units; null removes it. |
PATCH /v1/projects/{id}
curl -X PATCH https://api.usdf.fi/v1/projects/{id} \
-H "Authorization: Bearer $SESSION" \
-H "Content-Type: application/json" \
-d '{"budget_units": "50000000"}'POST/v1/projects/{id}/archive
Its keys leave it and keep working in no project. It is never changed again, and its usage rows keep it. This cannot be undone.
Auth: Session, not an API key: Authorization: Bearer <session token>. See Sign in.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Path. The project's id. |
POST /v1/projects/{id}/archive
curl -X POST https://api.usdf.fi/v1/projects/{id}/archive \
-H "Authorization: Bearer $SESSION"