Composio Organization Management API

openapi: 3.0.0
info:
  version: 3.0.0
  title: Composio Platform Account Management Organization Management API
  description: ''
  contact:
    name: Composio Support
    url: https://composio.dev/support
    email: support@composio.dev
  license:
    name: Proprietary
    url: https://composio.dev/terms
servers:
- url: https://backend.composio.dev
  description: PRODUCTION API
tags:
- name: Organization Management
paths:
  /api/v3/org/owner/project/list:
    get:
      summary: List all projects
      description: Retrieves all projects belonging to the authenticated organization. Projects are returned in descending order of creation date (newest first). This endpoint is useful for displaying project selection in dashboards or for integrations that need to list all available projects.
      tags:
      - Organization Management
      operationId: getOrgOwnerProjectList
      security:
      - OrgApiKeyAuth: []
      parameters:
      - schema:
          type: number
          nullable: true
        required: false
        description: Number of items per page, max allowed is 1000
        name: limit
        in: query
      - schema:
          type: string
        required: false
        description: Cursor for pagination. The cursor is a base64 encoded string of the page and limit. The page is the page number and the limit is the number of items per page. The cursor is used to paginate through the items. The cursor is not required for the first page.
        name: cursor
        in: query
      responses:
        '200':
          description: Projects retrieved successfully with pagination. Returns an array of projects with pagination info.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: projectId
                          description: Unique identifier for the project
                          example: pr_1a2b3c4d5e6f
                        org_id:
                          type: string
                          format: orgId
                          description: Identifier of the organization that owns this project
                          example: ok_1a2b3c4d5e6f
                        name:
                          type: string
                          description: Name of the project
                          example: My Awesome Project
                        email:
                          type: string
                          description: Email address associated with the project
                          example: project-123@composio.dev
                        created_at:
                          type: string
                          description: ISO timestamp when the project was created
                          example: '2023-05-16T14:30:00.000Z'
                        updated_at:
                          type: string
                          description: ISO timestamp when the project was last updated
                          example: '2023-05-18T09:15:30.000Z'
                        webhook_url:
                          type: string
                          nullable: true
                          format: uri
                          description: 'DEPRECATED: Use GET /api/v3/webhook_subscriptions instead. Legacy project-level webhook URL.'
                          example: https://example.com/webhook
                          deprecated: true
                        event_webhook_url:
                          type: string
                          nullable: true
                          format: uri
                          description: 'DEPRECATED: No longer used.'
                          example: https://example.com/events
                          deprecated: true
                        webhook_secret:
                          type: string
                          nullable: true
                          description: 'DEPRECATED: Use GET /api/v3/webhook_subscriptions instead. Legacy project-level webhook secret.'
                          example: whsec_abcdef123456789
                          deprecated: true
                        triggers_enabled:
                          type: boolean
                          description: Whether triggers are enabled for this project
                          example: true
                        last_subscribed_at:
                          type: string
                          nullable: true
                          format: date-time
                          description: ISO timestamp when the project last subscribed to updates
                          example: '2023-05-17T10:00:00.000Z'
                        is_new_webhook:
                          type: boolean
                          description: 'Deprecated: Please refer to webhook_version instead. True indicates if the webhook configuration is using the previous new format (V2). False indicates the oldest format (V1)'
                          example: true
                          deprecated: true
                        webhook_version:
                          type: string
                          enum:
                          - V1
                          - V2
                          - V3
                          description: Payload format version for Pusher real-time events only. For webhook configuration, use GET /api/v3/webhook_subscriptions.
                          example: V2
                        deleted:
                          type: boolean
                          description: Whether this project has been soft-deleted
                          example: false
                      required:
                      - id
                      - org_id
                      - name
                      - email
                      - created_at
                      - updated_at
                      - webhook_url
                      - event_webhook_url
                      - webhook_secret
                      - webhook_version
                      - deleted
                  next_cursor:
                    type: string
                    nullable: true
                  total_pages:
                    type: number
                  current_page:
                    type: number
                  total_items:
                    type: number
                required:
                - data
                - total_pages
                - current_page
                - total_items
        '400':
          description: Bad request. This may occur if there are invalid query parameters or the request is malformed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized. Authentication is required or the provided credentials are invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error. An unexpected error occurred while processing the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v3/org/owner/project/{nano_id}:
    get:
      summary: Get project details by ID With Org Api key
      description: Retrieves detailed information about a specific project using its unique identifier. This endpoint provides complete project configuration including webhook URLs, creation and update timestamps, and webhook secrets. Use this endpoint to inspect project settings or verify project configuration.
      tags:
      - Organization Management
      operationId: getOrgOwnerProjectByNanoId
      security:
      - OrgApiKeyAuth: []
      parameters:
      - schema:
          type: string
          format: projectId
          description: Unique identifier (Nano ID) of the project to retrieve
          example: pr_1a2b3c4d5e6f
        required: true
        description: Unique identifier (Nano ID) of the project to retrieve
        name: nano_id
        in: path
      responses:
        '200':
          description: Project retrieved successfully. Returns a complete project object with all configuration details and associated API keys.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: projectId
                    description: Unique identifier for the project
                    example: pr_1a2b3c4d5e6f
                  org_id:
                    type: string
                    format: orgId
                    description: Identifier of the organization that owns this project
                    example: ok_1a2b3c4d5e6f
                  name:
                    type: string
                    description: Name of the project
                    example: My Awesome Project
                  email:
                    type: string
                    description: Email address associated with the project
                    example: project-123@composio.dev
                  created_at:
                    type: string
                    description: ISO timestamp when the project was created
                    example: '2023-05-16T14:30:00.000Z'
                  updated_at:
                    type: string
                    description: ISO timestamp when the project was last updated
                    example: '2023-05-18T09:15:30.000Z'
                  webhook_url:
                    type: string
                    nullable: true
                    format: uri
                    description: 'DEPRECATED: Use GET /api/v3/webhook_subscriptions instead. Legacy project-level webhook URL.'
                    example: https://example.com/webhook
                    deprecated: true
                  event_webhook_url:
                    type: string
                    nullable: true
                    format: uri
                    description: 'DEPRECATED: No longer used.'
                    example: https://example.com/events
                    deprecated: true
                  webhook_secret:
                    type: string
                    nullable: true
                    description: 'DEPRECATED: Use GET /api/v3/webhook_subscriptions instead. Legacy project-level webhook secret.'
                    example: whsec_abcdef123456789
                    deprecated: true
                  triggers_enabled:
                    type: boolean
                    description: Whether triggers are enabled for this project
                    example: true
                  last_subscribed_at:
                    type: string
                    nullable: true
                    format: date-time
                    description: ISO timestamp when the project last subscribed to updates
                    example: '2023-05-17T10:00:00.000Z'
                  is_new_webhook:
                    type: boolean
                    description: 'Deprecated: Please refer to webhook_version instead. True indicates if the webhook configuration is using the previous new format (V2). False indicates the oldest format (V1)'
                    example: true
                    deprecated: true
                  webhook_version:
                    type: string
                    enum:
                    - V1
                    - V2
                    - V3
                    description: Payload format version for Pusher real-time events only. For webhook configuration, use GET /api/v3/webhook_subscriptions.
                    example: V2
                  deleted:
                    type: boolean
                    description: Whether this project has been soft-deleted
                    example: false
                  api_keys:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Unique identifier for the API key
                          example: 01H4DKRF5SMP7NQCA3BWT0JYB6
                        name:
                          type: string
                          description: User-defined name for the API key
                          example: Production Server Key
                        key:
                          type: string
                          description: The actual API key value used for authentication
                          example: ak_a1b2c3d4e5f6g7h8i9j0
                        created_at:
                          type: string
                          format: date-time
                          description: ISO 8601 timestamp when the API key was created
                          example: '2023-07-15T14:30:00.000Z'
                      required:
                      - id
                      - name
                      - key
                      - created_at
                    description: Array of API keys for the project, including their properties
                required:
                - id
                - org_id
                - name
                - email
                - created_at
                - updated_at
                - webhook_url
                - event_webhook_url
                - webhook_secret
                - webhook_version
                - deleted
                - api_keys
        '400':
          description: Bad request. This may occur if the project ID format is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized. Authentication is required or the provided credentials are invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found. The specified project does not exist or you do not have access to it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error. An unexpected error occurred while processing the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete a project
      description: Soft-deletes a project within the organization by its unique identifier. When a project is deleted, it is marked as deleted but not immediately removed from the database. This operation affects all resources associated with the project including API keys, webhook configurations, and connected services. This action cannot be undone through the API.
      tags:
      - Organization Management
      operationId: deleteOrgOwnerProjectByNanoId
      security:
      - OrgApiKeyAuth: []
      parameters:
      - schema:
          type: string
          format: projectId
          description: Unique identifier (Nano ID) of the project to delete
          example: pr_1a2b3c4d5e6f
        required: true
        description: Unique identifier (Nano ID) of the project to delete
        name: nano_id
        in: path
      responses:
        '200':
          description: Project successfully deleted. The project has been marked as deleted in the system.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - success
                    description: Status indicating successful deletion
                    example: success
                required:
                - status
                description: Response indicating successful project deletion
        '400':
          description: Bad request. The project ID may be invalid or in an incorrect format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized. Authentication is required or the provided credentials are invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden. You do not have permission to delete this project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found. The specified project does not exist or has already been deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error. An unexpected error occurred while processing the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v3/org/owner/project/{nano_id}/regenerate_api_key:
    post:
      summary: Delete and generate new API key for project
      description: Generates a new API key for the specified project, invalidating any existing API keys for that project. This operation creates a fresh API key with a new random name and key value. All existing API keys for this project will be marked as deleted.
      tags:
      - Organization Management
      operationId: postOrgOwnerProjectByNanoIdRegenerateApiKey
      security:
      - OrgApiKeyAuth: []
      parameters:
      - schema:
          type: string
          format: projectId
          description: Unique identifier (Nano ID) of the project to regenerate API key for
          example: pr_1a2b3c4d5e6f
        required: true
        description: Unique identifier (Nano ID) of the project to regenerate API key for
        name: nano_id
        in: path
      responses:
        '200':
          description: API key regenerated successfully. Returns the new API key details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  api_key:
                    type: object
                    properties:
                      id:
                        type: string
                        description: Unique identifier for the API key
                        example: 01H4DKRF5SMP7NQCA3BWT0JYB6
                      name:
                        type: string
                        description: Name of the API key
                        example: epic_avatar
                      key:
                        type: string
                        description: The newly generated API key value
                        example: ak_a1b2c3d4e5f6g7h8i9j0
                      created_at:
                        type: string
                        description: ISO timestamp when the API key was created
                        example: '2023-05-16T14:30:00.000Z'
                    required:
                    - id
                    - name
                    - key
                    - created_at
                    description: The newly generated API key for this project
                  message:
                    type: string
                    description: Success message
                    example: API key regenerated successfully
                required:
                - api_key
                - message
        '400':
          description: Bad request. The project ID may be invalid or in an incorrect format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized. Authentication is required or the provided credentials are invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found. The specified project does not exist or you do not have access to it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error. An unexpected error occurred while processing the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v3/org/consumer/project/resolve:
    post:
      summary: Resolve the organization consumer project
      description: Finds the authenticated organization's single CONSUMER project and provisions it if absent. This endpoint is idempotent and never returns consumer API keys.
      tags:
      - Organization Management
      operationId: postOrgConsumerProjectResolve
      security:
      - UserApiKeyAuth: []
      parameters:
      - schema:
          type: string
          minLength: 1
          description: User API key used to authenticate the request.
          example: uak_a1b2c3d4e5f6g7h8i9j0
        required: true
        name: x-user-api-key
        in: header
      - schema:
          type: string
          format: orgId
          description: Organization nano ID that scopes the user API key resolution.
          example: ok_1a2b3c4d5e6f
        required: true
        name: x-org-id
        in: header
      responses:
        '200':
          description: Consumer project resolved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  project_id:
                    type: string
                    format: uuid
                    description: UUID of the resolved consumer project.
                  project_nano_id:
                    type: string
                    format: projectId
                    description: Nano ID of the resolved consumer project.
                  project_name:
                    type: string
                    description: Name of the resolved consumer project.
                  org_id:
                    type: string
                    format: orgId
                    description: Organization nano ID that owns the consumer project.
                  project_type:
                    type: string
                    enum:
                    - CONSUMER
                    description: Resolved project type.
                  consumer_user_id:
                    type: string
                    description: Derived internal Composio user ID for the authenticated user in this consumer org context.
                required:
                - project_id
                - project_nano_id
                - project_name
                - org_id
                - project_type
                - consumer_user_id
        '400':
          description: Bad request. x-org-id is required for user API key authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized. A valid user API key is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Org not found or deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v3/org/consumer/connected_toolkits:
    get:
      summary: List active connected toolkits for a consumer user
      description: Resolves the organization's single CONSUMER project and returns the distinct toolkit slugs for which the specified consumer user has an ACTIVE connection.
      tags:
      - Organization Management
      operationId: getOrgConsumerConnectedToolkits
      security:
      - UserApiKeyAuth: []
      parameters:
      - schema:
          type: string
          minLength: 1
          description: Consumer user ID to inspect within the consumer project.
        required: true
        description: Consumer user ID to inspect within the consumer project.
        name: user_id
        in: query
      - schema:
          type: string
          minLength: 1
          description: User API key used to authenticate the request.
          example: uak_a1b2c3d4e5f6g7h8i9j0
        required: true
        name: x-user-api-key
        in: header
      - schema:
          type: string
          minLength: 1
          description: Organization nano ID that owns the consumer project.
        required: true
        description: Organization nano ID that owns the consumer project.
        name: x-org-id
        in: header
      responses:
        '200':
          description: Active consumer connected toolkits retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  toolkits:
                    type: array
                    items:
                      type: string
                    description: Distinct active toolkit slugs.
                required:
                - toolkits
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: User not found in organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            code:
              type: number
            slug:
              type: string
            status:
              type: number
            request_id:
              type: string
            suggested_fix:
              type: string
            errors:
              type: array
              items:
                type: string
          required:
          - message
          - code
          - slug
          - status
      required:
      - error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Project API key authentication
    UserApiKeyAuth:
      type: apiKey
      in: header
      name: x-user-api-key
      description: User API key authentication
    CookieAuth:
      type: apiKey
      in: cookie
      name: authToken
      description: Cookie-based session authentication
    OrgApiKeyAuth:
      type: apiKey
      in: header
      name: x-org-api-key
      description: Organization API key authentication