Cognee agent connections API

openapi: 3.2.0
info:
  title: Cognee agent connections API
  description: Cognee API with Bearer token and Cookie auth
  version: 1.0.0
servers:
- url: https://{tenant}.aws.cognee.ai
  description: 'Cognee Cloud: your tenant pod, named in the platform.cognee.ai dashboard'
  variables:
    tenant:
      default: your-tenant
      description: Your tenant name, shown in the Cognee Cloud dashboard
- url: http://localhost:8000
  description: 'Self-hosted: a locally running cognee server'
security:
- BearerAuth: []
- ApiKeyAuth: []
tags:
- name: agent connections
  description: Endpoints for registering, unregistering, and inspecting agent connections to the instance.
paths:
  /api/v1/agents/connections:
    get:
      tags:
      - agent connections
      summary: List Agents Connections
      description: 'List agents connections — GET /api/v1/agents/connections.


        ## Query Parameters

        - **active_only** (bool): When true, restricts results to connections currently

        considered active. Defaults to True.

        - **agent_id** (Optional[UUID]): Filter connections by agent user ID. Only returns

        connections belonging to this specific agent.

        - **include_sources** (bool): When true, includes the source breakdown for each

        returned connection. Defaults to True.

        - **limit** (int): Maximum number of rows to return. Defaults to 50.

        - **offset** (int): Number of rows to skip for pagination. Defaults to 0.

        - **range** (Literal[''24h'', ''7d'', ''30d'', ''all'']): One of: ''24h'', ''7d'', ''30d'', ''all''.

        Defaults to ''30d''.

        - **status** (Optional[Literal[''active'', ''inactive'', ''unknown'']]): One of: ''active'',

        ''inactive'', ''unknown''.'
      operationId: list_agents_connections_api_v1_agents_connections_get
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - name: agent_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Filter connections by agent user ID. Only returns connections belonging to this specific agent.
          title: Agent Id
        description: Filter connections by agent user ID. Only returns connections belonging to this specific agent.
      - name: range
        in: query
        required: false
        schema:
          enum:
          - 24h
          - 7d
          - 30d
          - all
          type: string
          default: 30d
          title: Range
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - enum:
            - active
            - inactive
            - unknown
            type: string
          - type: 'null'
          title: Status
      - name: include_sources
        in: query
        required: false
        schema:
          type: boolean
          default: true
          title: Include Sources
      - name: active_only
        in: query
        required: false
        schema:
          type: boolean
          default: true
          title: Active Only
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 500
          minimum: 1
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/agents/connections/me:
    get:
      tags:
      - agent connections
      summary: Get My Connection Detail
      description: 'Get my connection detail — GET /api/v1/agents/connections/me.


        ## Query Parameters

        - **agent_session_name** (Optional[str]): Filter by connection name. A named lookup also

        returns inactive (unregistered) connections; check agent.status. Uses the authenticated

        user''s ID as the agent ID.'
      operationId: get_my_connection_detail_api_v1_agents_connections_me_get
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - name: agent_session_name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by connection name. A named lookup also returns inactive (unregistered) connections; check agent.status. Uses the authenticated user's ID as the agent ID.
          title: Agent Session Name
        description: Filter by connection name. A named lookup also returns inactive (unregistered) connections; check agent.status. Uses the authenticated user's ID as the agent ID.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/agents/connections/{agent_id}:
    get:
      tags:
      - agent connections
      summary: Get Connection Detail
      description: 'Get connection detail — GET /api/v1/agents/connections/\{agent_id\}.


        ## Path Parameters

        - **agent_id** (UUID): The agent''s user ID (from GET /api/v1/agents/list).


        ## Query Parameters

        - **agent_session_name** (Optional[str]): Filter by connection name within the agent''s

        connections. A named lookup also returns inactive (unregistered) connections; check

        agent.status.'
      operationId: get_connection_detail_api_v1_agents_connections__agent_id__get
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Agent Id
      - name: agent_session_name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by connection name within the agent's connections. A named lookup also returns inactive (unregistered) connections; check agent.status.
          title: Agent Session Name
        description: Filter by connection name within the agent's connections. A named lookup also returns inactive (unregistered) connections; check agent.status.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/agents/register:
    post:
      tags:
      - agent connections
      summary: Register Agent Endpoint
      description: 'Register agent endpoint — POST /api/v1/agents/register.


        ## Request Parameters

        - **agent_session_name** (str): A unique name for this agent connection. Combined with the

        authenticated user''s ID to identify the connection.

        - **dataset_ids** (List[str]): UUIDs of the datasets (from GET /api/v1/datasets).

        - **dataset_names** (List[str]): Names of the datasets this agent connection reads

        from and writes to.

        - **memory_mode** (Literal[''session'', ''cognee'', ''hybrid'', ''none'', ''unknown'']): One of:

        ''session'', ''cognee'', ''hybrid'', ''none'', ''unknown''. Defaults to ''unknown''.

        - **metadata** (Dict[str, Any]): Free-form metadata object.

        - **origin_function** (Optional[str]): Name of the calling function or tool that

        triggered the registration, stored on the connection.

        - **session_id** (Optional[str]): Client-supplied session identifier — the same value passed

        as session_id to POST /api/v1/remember.

        - **source** (Literal[''agent_memory'', ''session_trace'', ''serve'', ''api_key'', ''mcp'', ''api'']):

        One of: ''agent_memory'', ''session_trace'', ''serve'', ''api_key'', ''mcp'', ''api''. Defaults to

        ''api''.

        - **type** (str): Connection type label recorded for the registered agent. Defaults

        to ''api''.'
      operationId: register_agent_endpoint_api_v1_agents_register_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterAgentRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
  /api/v1/agents/unregister:
    post:
      tags:
      - agent connections
      summary: Unregister Agent Endpoint
      description: 'Unregister agent endpoint — POST /api/v1/agents/unregister.


        ## Request Parameters

        - **agent_session_name** (str): The name used when registering the connection. Combined with

        the authenticated user''s ID to identify which connection to deactivate.'
      operationId: unregister_agent_endpoint_api_v1_agents_unregister_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnregisterAgentRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentModeDTO'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    RegisterAgentRequest:
      properties:
        agent_session_name:
          type: string
          title: Agent Session Name
          description: A unique name for this agent connection. Combined with the authenticated user's ID to identify the connection.
        type:
          type: string
          title: Type
          default: api
        memory_mode:
          type: string
          enum:
          - session
          - cognee
          - hybrid
          - none
          - unknown
          title: Memory Mode
          default: unknown
        session_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Id
        dataset_ids:
          items:
            type: string
          type: array
          title: Dataset Ids
        dataset_names:
          items:
            type: string
          type: array
          title: Dataset Names
        source:
          type: string
          enum:
          - agent_memory
          - session_trace
          - serve
          - api_key
          - mcp
          - api
          title: Source
          default: api
        origin_function:
          anyOf:
          - type: string
          - type: 'null'
          title: Origin Function
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
      type: object
      required:
      - agent_session_name
      title: RegisterAgentRequest
    AgentModeDTO:
      properties:
        activeAgents:
          type: integer
          title: Activeagents
      type: object
      required:
      - activeAgents
      title: AgentModeDTO
    UnregisterAgentRequest:
      properties:
        agent_session_name:
          type: string
          title: Agent Session Name
          description: The name used when registering the connection. Combined with the authenticated user's ID to identify which connection to deactivate.
      type: object
      required:
      - agent_session_name
      title: UnregisterAgentRequest
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    CookieAuth:
      type: apiKey
      in: cookie
      name: auth_token
x-provenance:
  method: harvested
  publisher: Cognee
  source: https://docs.cognee.ai/cognee_openapi_spec.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)