Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | --- |
| 2 | title: Projects |
| 3 | description: "Projects API endpoints" |
| 4 | --- |
| 5 | |
| 6 | {/* Auto-generated from OpenAPI spec. Edit the overview at api-overviews/projects.mdx, not this file. */} |
| 7 | |
| 8 | Projects are Composio's multi-tenancy primitive. Every Composio account belongs to an **organization**. Inside an organization, **projects** are isolated environments that scope your API keys, connected accounts, auth configs, and webhook configurations. Resources in one project are not accessible from another. |
| 9 | |
| 10 | ```mermaid |
| 11 | graph LR |
| 12 | ORG["Organization (org_xxx)"] --- P1["Project: Production (proj_xxx)"] |
| 13 | ORG --- P2["Project: Staging (proj_xxx)"] |
| 14 | ORG --- TM["Team Members"] |
| 15 | P1 --- A1["API Keys"] |
| 16 | P1 --- A2["Connected Accounts"] |
| 17 | P1 --- A3["Auth Configs"] |
| 18 | P1 --- A4["Webhook Config"] |
| 19 | P2 --- B1["..."] |
| 20 | ``` |
| 21 | |
| 22 | Common reasons to use multiple projects: |
| 23 | |
| 24 | - **Separate environments**: keep production and staging isolated |
| 25 | - **Separate products**: keep resources for different apps independent |
| 26 | - **Client isolation**: give each client their own project with separate credentials and data |
| 27 | |
| 28 | ## Managing projects |
| 29 | |
| 30 | Manage projects from the [dashboard](https://dashboard.composio.dev/~/org/) or via the API using an **organization API key** (`x-org-api-key`). |
| 31 | |
| 32 | <Callout type="info"> |
| 33 | Project management endpoints use the `x-org-api-key` header, not the regular `x-api-key`. Find your org API key in the dashboard under **Settings > Organization**. |
| 34 | </Callout> |
| 35 | |
| 36 | There is no limit on the number of projects per organization. Project names must be unique within the organization. Create a project with `should_create_api_key: true` to get an API key back in the response: |
| 37 | |
| 38 | The Python SDK also needs `COMPOSIO_API_KEY` to initialize. Its generated organization client selects the organization key for this operation. |
| 39 | |
| 40 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 41 | <Tab value="Python"> |
| 42 | ```python |
| 43 | import os |
| 44 | from composio import Composio |
| 45 | |
| 46 | composio = Composio(org_api_key=os.environ["COMPOSIO_ORG_API_KEY"]) |
| 47 | project = composio.client.org.owner.project.create( |
| 48 | name="my-staging-project", |
| 49 | should_create_api_key=True, |
| 50 | ) |
| 51 | print(project) |
| 52 | ``` |
| 53 | </Tab> |
| 54 | <Tab value="TypeScript"> |
| 55 | ```typescript |
| 56 | import { Composio } from '@composio/core'; |
| 57 | |
| 58 | const composio = new Composio({ |
| 59 | apiKey: null, |
| 60 | userApiKey: null, |
| 61 | orgApiKey: process.env.COMPOSIO_ORG_API_KEY, |
| 62 | }); |
| 63 | const project = await composio.getClient().post<unknown>('/api/v3.1/org/owner/project/new', { |
| 64 | body: { name: 'my-staging-project', should_create_api_key: true }, |
| 65 | }); |
| 66 | console.log(project); |
| 67 | ``` |
| 68 | </Tab> |
| 69 | <Tab value="API"> |
| 70 | ```bash |
| 71 | curl -X POST https://backend.composio.dev/api/v3.1/org/owner/project/new \ |
| 72 | -H "x-org-api-key: $COMPOSIO_ORG_API_KEY" \ |
| 73 | -H "Content-Type: application/json" \ |
| 74 | -d '{ |
| 75 | "name": "my-staging-project", |
| 76 | "should_create_api_key": true |
| 77 | }' |
| 78 | ``` |
| 79 | </Tab> |
| 80 | </Tabs> |
| 81 | |
| 82 | ```json |
| 83 | { |
| 84 | "id": "proj_abc123xyz456", |
| 85 | "name": "my-staging-project", |
| 86 | "api_key": "ak_abc123xyz456" |
| 87 | } |
| 88 | ``` |
| 89 | |
| 90 | The list endpoint supports pagination with `limit` and `cursor`; getting a project by ID returns the full project object including its API keys. |
| 91 | |
| 92 | ## Project settings |
| 93 | |
| 94 | Each project has settings that control security, logging, and display behavior. The project detail endpoints return current configuration for inspection. Use **Settings > Project Settings** in the [dashboard](https://dashboard.composio.dev/~/project/settings/general) to update project settings. |
| 95 | |
| 96 | Notable security setting: `require_mcp_api_key`, when `true`, requires MCP server requests to include a valid `x-api-key` header. This defaults to `true` for organizations created on or after March 5, 2026. |
| 97 | |
| 98 | ## Endpoints |
| 99 | |
| 100 | <ApiEndpointsTable endpoints={[{"method":"GET","pathV31":"/api/v3.1/org/project/list","pathV3":"/api/v3/org/project/list","summary":"List all projects","href":"/reference/v3/api-reference/projects/getOrgProjectList"},{"method":"POST","pathV31":"/api/v3.1/org/owner/project/new","pathV3":"/api/v3/org/owner/project/new","summary":"Create a new project","href":"/reference/v3/api-reference/projects/postOrgOwnerProjectNew"},{"method":"GET","pathV31":"/api/v3.1/org/owner/project/list","pathV3":"/api/v3/org/owner/project/list","summary":"List all projects","href":"/reference/v3/api-reference/projects/getOrgOwnerProjectList"},{"method":"GET","pathV31":"/api/v3.1/org/owner/project/{nano_id}","pathV3":"/api/v3/org/owner/project/{nano_id}","summary":"Get project details by ID With Org Api key","href":"/reference/v3/api-reference/projects/getOrgOwnerProjectByNanoId"},{"method":"DELETE","pathV31":"/api/v3.1/org/owner/project/{nano_id}","pathV3":"/api/v3/org/owner/project/{nano_id}","summary":"Delete a project","href":"/reference/v3/api-reference/projects/deleteOrgOwnerProjectByNanoId"},{"method":"POST","pathV31":"/api/v3.1/org/owner/project/{nano_id}/regenerate_api_key","pathV3":"/api/v3/org/owner/project/{nano_id}/regenerate_api_key","summary":"Delete and generate new API key for project","href":"/reference/v3/api-reference/projects/postOrgOwnerProjectByNanoIdRegenerateApiKey"}]} /> |