Projects
Projects are organizational units that allow you to group related agents, users, files, and other resources together. They provide a way to manage resources at a higher level and maintain clean separation between different use cases or applications.Overview
Projects provide several benefits:- Organization: Group related resources together logically
- Management: Administer resources at the project level
- Isolation: Keep resources separate between different applications
- Deployment: Deploy multiple templates or configurations without conflicts
Project Properties
A project includes:id
: Unique identifiercanonical_name
: Machine-readable name (unique per developer)name
: Human-readable display namemetadata
: Custom attributes for the project
Project Relationships
Projects have a one-to-many relationship with resources:- Each agent belongs to exactly one project
- Each user belongs to exactly one project
- Each file belongs to exactly one project
project
field. If not specified, resources are automatically assigned to the “default” project.
Default Project
Every developer automatically receives a “default” project when they first interact with the API. This project:- Cannot be deleted
- Has a canonical name of “default”
- Contains all previously created resources (pre-dating the projects feature)
- Serves as a fallback for resources created without a project specification
API Operations
Projects support standard CRUD operations:GET /projects
: List all projects for a developerPOST /projects
: Create a new projectGET /projects/{id}
: Retrieve a specific projectPUT /projects/{id}
: Update a projectPATCH /projects/{id}
: Partially update a projectDELETE /projects/{id}
: Delete a project (except the default project)
Usage Examples
Creating a Project
Creating a Resource in a Project
When creating a resource such as an agent, specify the project canonical name:Future Capabilities
Projects are designed with future extensibility in mind. Planned enhancements include:- Project-specific API keys for more granular access control
- Usage tracking and billing at the project level
- Enhanced permissions and role-based access control
- Cross-project resource sharing capabilities
Best Practices
- Use meaningful canonical names for projects that reflect their purpose
- Group resources by logical application or team
- Use metadata to add custom attributes for filtering and organization
- Create separate projects for development, staging, and production environments