Projects

Projects provide the first path segment for files. Use a project name in a file path, or use its ID in collection filters.

Project object

Field	Type	Description
`type`	string	Always `project`.
`id`	string	Project identifier.
`name`	string	Project name.
`site_url`	string or `null`	Project site URL, when one is set.
`storage_region`	string	Where the project's files are stored. Always `us-east` for new projects.
`default_visibility`	string	`public`, `unlisted`, or `private`.
`default_expires_in`	integer or `null`	Default file expiration in seconds.
`file_count`	integer	Number of ready files in the project.
`size_bytes`	integer	Total bytes in ready files.
`created_at`	string	ISO 8601 creation time.
`updated_at`	string	ISO 8601 update time.

List projects when the API key has read permission on each project (an organization scope or a project scope with an empty prefix). The API filters inaccessible projects before it applies the cursor.

Query parameters

Parameter	Type	Required	Description
`limit`	integer	No	Number of items, from 1 through 200. Defaults to 50.
`cursor`	string	No	Opaque cursor from the previous response.

Response fields

Field	Type	Description
`items`	array	Project objects.
`next_cursor`	string or `null`	Cursor for the next page, or `null` when there is no next page.

Returns 200 OK.

Request

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

Response

200 OK

{
  "items": [
    {
      "type": "project",
      "id": "p_1a2b",
      "name": "reports",
      "site_url": null,
      "storage_region": "us-east",
      "default_visibility": "unlisted",
      "default_expires_in": null,
      "file_count": 12,
      "size_bytes": 482130,
      "created_at": "2026-03-01T12:00:00.000Z",
      "updated_at": "2026-03-02T12:00:00.000Z"
    }
  ],
  "next_cursor": null
}

Errors

unauthorized (401), invalid_agent_label (400), invalid_query (400), internal_error (500).

Get a project

GET /v1/projects/:project

Return one project by name. Project names are matched case-insensitively, and the API key must have read permission on the whole project (an empty path prefix).

Path parameters

Parameter	Type	Required	Description
`project`	string	Yes	URL-encoded project name.

Response fields

Returns a project object.

Returns 200 OK.

Request

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

Response

200 OK

{
  "type": "project",
  "id": "p_1a2b",
  "name": "reports",
  "site_url": null,
  "storage_region": "us-east",
  "default_visibility": "unlisted",
  "default_expires_in": null,
  "file_count": 12,
  "size_bytes": 482130,
  "created_at": "2026-03-01T12:00:00.000Z",
  "updated_at": "2026-03-02T12:00:00.000Z"
}

Errors

unauthorized (401), invalid_agent_label (400), project_not_found (404), forbidden (403), internal_error (500).

Create a project

POST /v1/projects

Create a project. The API key must have organization-level write permission; a project-scoped key cannot create a project.

Request body

Send JSON with Content-Type: application/json.

Field	Type	Required	Description
`name`	string	Yes	1–100 characters. The final name must start with a letter or digit and contain only letters, digits, `.`, `_`, and `-`.
`default_visibility`	string	No	`public`, `unlisted`, or `private`. Defaults to `unlisted`.
`default_expires_in`	integer or `null`	No	Positive seconds up to 31,536,000 (one year), or `null`.

Returns 201 Created with a project object. The API route does not accept site_url on create.

Response fields

Returns a project object.

Request

curl -X POST https://agentfs.cloud/v1/projects \
  -H "Authorization: Bearer $AGENTFS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "reports",
    "default_visibility": "unlisted",
    "default_expires_in": 86400
  }'

Response

201 Created

{
  "type": "project",
  "id": "p_1a2b",
  "name": "reports",
  "site_url": null,
  "storage_region": "us-east",
  "default_visibility": "unlisted",
  "default_expires_in": 86400,
  "file_count": 0,
  "size_bytes": 0,
  "created_at": "2026-03-02T12:00:00.000Z",
  "updated_at": "2026-03-02T12:00:00.000Z"
}

Errors

unauthorized (401), invalid_agent_label (400), forbidden (403), invalid_project (400), project_exists (409), region_unavailable (422), project_create_failed (500), internal_error (500).

Update project settings

PATCH /v1/projects/:project

Update a project's default visibility or expiration. The API key must have write permission for the project.

Path parameters

Parameter	Type	Required	Description
`project`	string	Yes	URL-encoded project name.

Request body

Send JSON with Content-Type: application/json. Include at least one field.

Field	Type	Required	Description
`default_visibility`	string	No	`public`, `unlisted`, or `private`.
`default_expires_in`	integer or `null`	No	Positive seconds up to 31,536,000, or `null`. Omit it to keep the current value.
`storage_region`	string	No	Do not send this field. Any supplied value is rejected because a project's storage region cannot change.

Returns 200 OK with the updated project object.

Response fields

Returns a project object.

Request

curl -X PATCH https://agentfs.cloud/v1/projects/reports \
  -H "Authorization: Bearer $AGENTFS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"default_visibility":"public"}'

Response

200 OK

{
  "type": "project",
  "id": "p_1a2b",
  "name": "reports",
  "site_url": null,
  "storage_region": "us-east",
  "default_visibility": "public",
  "default_expires_in": null,
  "file_count": 12,
  "size_bytes": 482130,
  "created_at": "2026-03-01T12:00:00.000Z",
  "updated_at": "2026-03-02T12:01:00.000Z"
}

Errors

unauthorized (401), invalid_agent_label (400), invalid_project_settings (400), jurisdiction_immutable (409), project_not_found (404), forbidden (403), internal_error (500).

Delete a project

DELETE /v1/projects/:project

Delete a project the API key can delete. The key must have delete permission for the project.

Only team owners and admins can delete a project; for an API key, that is the role of the key's owner. By default, the project must contain no files. Pass recursive=true to delete its files and folders with the project. The rows are deleted at once, whatever the project's size, and the stored bytes within the hour.

Path parameters

Parameter	Type	Required	Description
`project`	string	Yes	URL-encoded project name.

Query parameters

Parameter	Type	Required	Description
`recursive`	string	No	Delete contents only when the value is exactly `true`. Any other value behaves as `false`.

Response

Returns 204 No Content with an empty body.

204 No Content

HTTP/1.1 204 No Content

Request

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

Errors

unauthorized (401), invalid_agent_label (400), project_not_found (404), forbidden (403), project_not_empty (409), internal_error (500).

On this page