About the Projects API

The Projects API creates, lists, renames, and deletes projects. Projects are served under /api/projects, alongside the Agents API.

​

What Projects Are

A project groups, within an organization, the blueprints for one agent effort and everything derived from them. Each project has a prj_ id, a name, and an optional description.

• Blueprints live in a project when you register them there with project_id in Create Blueprint, or when you copy one in with Copy Blueprint. A blueprint’s project is fixed when it is created. To reuse a blueprint in another project, copy it.
• Evals, optimizations, and packages made from a blueprint in a project are in that project. You don’t pass a project_id when you create them. A blueprint promoted from an optimization trial lands in the run’s project too.
• Agent runs of a package in a project are in that project.

Each of these resources carries a project_id field, which is null outside any project. Their list endpoints take a project_id filter: a project’s prj_ id lists that project’s resources only, and none lists the resources outside any project. Without the filter, a list holds the resources outside projects plus those of every project you can see.

​

Who Can See a Project

• A project is visible to the user who created it and to the organization’s admins.
• A project created with a service-account API key is visible to every service-account key of the organization instead of a single user.
• Users with the viewer role have read-only access: they can’t create, change, or delete projects or what they hold.

Attempting to access a project you can’t see, including everything in it, results in an HTTP 404 response, as if it did not exist. A project you can see but not modify answers 403 when you try to change it or what it holds.

​

Who Owns a Project’s Jobs and Files

The jobs and output files of an eval, optimization, or agent run in a project belong to the project’s creator, whoever starts the run. This way, the creator can always read the outputs. In a project created with a service-account API key, they belong to no user. created_by on the run still records who started it. For the same reason, a run in a project may only read input files that the project’s creator can see. Any other input file returns 400 when the run is created.

​

Deleting a Project

Only an empty project can be deleted. Delete the blueprints, evals, optimizations, packages, and runs it holds first; until then, Delete Project returns 409.