API reference

Projects

Group keys under a monthly budget, and read usage by project.

On this page

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.

NameTypeRequiredDescription
orgstringNoQuery. A team the account is a member of: its projects.
statestringNoQuery. active (default), archived or all.
limitintegerNoQuery. How many projects to return.
beforestringNoQuery. The page.next_before of the previous page.

GET /v1/projects

curl
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.

NameTypeRequiredDescription
orgstringNoQuery. A team the account is a member of.
namestringYesThe project's name.
budget_unitsstring or integer or nullNoA monthly budget in USDF base units. Leave it out, or null, for none.

POST /v1/projects

curl
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.

NameTypeRequiredDescription
idstringYesPath. The project's id.

GET /v1/projects/{id}

curl
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.

NameTypeRequiredDescription
idstringYesPath. The project's id.
namestringNoThe project's name.
budget_unitsstring or integer or nullNoA monthly budget in USDF base units; null removes it.

PATCH /v1/projects/{id}

curl
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.

NameTypeRequiredDescription
idstringYesPath. The project's id.

POST /v1/projects/{id}/archive

curl
curl -X POST https://api.usdf.fi/v1/projects/{id}/archive \
  -H "Authorization: Bearer $SESSION"
Foundry documentation

Confirm it's you

Confirm to continue the action you started.

Checking confirmation options…