Projects

A project is the first segment of every file path, such as research/report.pdf. Use a bearer API key for these endpoints.

Create a project

Send JSON with a project name:

curl -sS -X POST https://agentfs.cloud/v1/projects \
  -H "Authorization: Bearer $AGENTFS_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "research",
    "default_visibility": "private",
    "default_expires_in": 604800
  }'

name is required, starts with a letter or number, and is at most 100 characters. It may contain letters, numbers, ., _, and -. Project names are case-insensitive.

The other accepted fields are:

The response has status 201:

{
  "type": "project",
  "id": "p_a13b",
  "name": "research",
  "site_url": null,
  "storage_region": "us-east",
  "default_visibility": "private",
  "default_expires_in": 604800,
  "file_count": 0,
  "size_bytes": 0,
  "created_at": "2026-04-01T12:00:00.000Z",
  "updated_at": "2026-04-01T12:00:00.000Z"
}

List projects

Call GET /v1/projects:

curl -sS "https://agentfs.cloud/v1/projects?limit=50" \
  -H "Authorization: Bearer $AGENTFS_KEY"

The response is { "items": [project objects], "next_cursor": "..." }. The default limit is 50 and the maximum is 200. Pass next_cursor back as cursor to get the next page. A key scoped to selected projects sees only those projects.

Get a project

Address a project by name:

curl -sS https://agentfs.cloud/v1/projects/research \
  -H "Authorization: Bearer $AGENTFS_KEY"

GET /v1/projects/:project returns one project object. URL-encode the name when needed.

Update project defaults

Use PATCH /v1/projects/:project with one or more settings:

curl -sS -X PATCH https://agentfs.cloud/v1/projects/research \
  -H "Authorization: Bearer $AGENTFS_KEY" \
  -H "content-type: application/json" \
  -d '{"default_visibility":"unlisted","default_expires_in":null}'

The API update body accepts default_visibility and default_expires_in. It must contain at least one setting. This API does not rename a project.

A file without its own visibility uses the project's current default_visibility, so a change applies to existing files at once. default_expires_in sets the expiry of files uploaded after the change; files already stored keep the expiry they were given.

Delete a project

Delete an empty project with:

curl -sS -X DELETE https://agentfs.cloud/v1/projects/research \
  -H "Authorization: Bearer $AGENTFS_KEY"

Only team owners and admins can delete a project; for an API key, that is the role of the key's owner. If the project contains files, the request returns 409 project_not_empty. Add recursive=true to delete the files and the project:

curl -sS -X DELETE "https://agentfs.cloud/v1/projects/research?recursive=true" \
  -H "Authorization: Bearer $AGENTFS_KEY"

A successful delete returns 204 with no body. The project and its files disappear at once, whatever the project's size; the stored bytes are removed within the hour.