DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS
API·CONCEPTS·PROJECTS

Projects

A Project is the top-level container in Onnie. It groups Tasks, Tables, Pages, and other content around a single initiative or team focus area. You can think of it as the unit of ownership: every piece of content lives inside exactly one project (or sits at workspace level before being assigned).

For the user-facing description of how to create and manage projects, see the Projects overview.

What a Project is in the API

The API represents a project as a first-class resource with its own UUID and alias_id. Because projects gate access to everything inside them — tasks, tables, pages — the eventual /projects endpoints will act as the entry point for any workspace traversal that starts from an initiative rather than a resource type.

Projects can be public (visible to all workspace members) or private (visible only to explicit project members and workspace admins). The API will reflect that visibility: a key that belongs to a workspace member who isn't a project member won't see private projects in list responses.

Project fields

When Projects are available via the API, a project object will expose the following fields:

FieldTypeNotes
idUUIDStable primary key. Never changes.
alias_idstring12-char base64 token generated from the UUID at creation time. Use this in human-readable URLs. It is not a slug — it's opaque and derived, not chosen.
namestringDisplay name of the project.
descriptionstring | nullFree-form description. Null if not set.
statusstringOne of: draft, active, paused, completed, archived.
is_privatebooleantrue if access is restricted to explicit project members.
start_datestring | nullISO-8601 date (date only, no time component).
end_datestring | nullISO-8601 date.
target_datestring | nullISO-8601 date.
iconstringIcon identifier (default: folder-kanban).
colorstringBrand color token (default: onnie).
lead_idUUID | nullUUID of the workspace member leading the project.
created_atstringISO-8601 timestamp.
updated_atstringISO-8601 timestamp.

Fields like onnie_md, metadata, and order_index are internal and will not be surfaced in API responses.

Projects sit at the top of the content hierarchy. Three module types live inside a project:

Tasks — the primary unit of work. Each task carries a project_id that you can use to filter the /tasks endpoint today: GET /api/public/v1/tasks?project_id=<uuid>. See Tasks.

Tables — structured data stores. A table belongs to a project and holds records. The /tables and /tables/{id}/records endpoints are available now; you can identify which project a table belongs to once project read endpoints land. See Tables, records & fields.

Pages — rich documents. The /pages endpoint surfaces page content; a project_id field on each page identifies its parent. See the Pages section.

Project scopes

Projects don't yet have dedicated API scopes. The Scope type currently covers tables:read, tables:write, pages:read, skills:read, and tasks:read. When project endpoints ship, projects:read and projects:write will be added to the scope registry and the key-minting UI.

Until then, the existing scopes give you indirect access to project content: tasks:read lets you filter tasks by project_id, and tables:read + pages:read let you read the content inside a project.

For the full scope table, see Scopes & permissions.

Available endpoints

Project-specific endpoints are not yet in the v1 API. The planned surface is /projects (list) and /projects/{id} (get one), with read access shipping before write.

//NOTE

Project endpoints are coming soon. Until they land, use tasks:read with the project_id filter on /api/public/v1/tasks to work with project-scoped task data. Check the Modules overview for the planned endpoint paths.