> ## Documentation Index > Fetch the complete documentation index at: https://docs.cognigy.com/llms.txt > Use this file to discover all available pages before exploring further. # List agents > Returns a list of agents with optional filtering, pagination, and sorting. ## OpenAPI ````yaml https://api-trial.cognigy.ai/swagger/openapi.json get /agents openapi: 3.0.3 info: contact: email: support@example.com name: API Support description: API for managing agents and related resources license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html termsOfService: http://swagger.io/terms/ title: Agents API version: '1.0' servers: - url: https://api-trial.cognigy.ai/v1 security: - ApiKey: [] tags: - name: Agents - name: Brand personas - name: Tools - name: Built-in tools - name: Skills - name: Built-in skills - name: MCP servers - name: Tool references paths: /agents: get: tags: - Agents summary: List agents description: >- Returns a list of agents with optional filtering, pagination, and sorting. parameters: - description: The unique identifier for the project to filter by. in: query name: projectId schema: type: string - description: The string to filter by name. The filter is case-insensitive. in: query name: filter schema: type: string - description: >- The maximum number of items to return, from 1 to 100. The default is 100. in: query name: limit schema: default: 100 type: integer - description: >- The number of items to skip before starting to return results. The default is 0. in: query name: skip schema: default: 0 type: integer - description: The sort order, either `asc` or `desc`. The default is `asc`. in: query name: sort schema: default: asc type: string - description: The cursor for the next page of results. in: query name: next schema: type: string - description: The cursor for the previous page of results. in: query name: previous schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/internal_agents.ListAgentsResponse' description: OK '400': content: application/json: schema: $ref: >- #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailBadRequest description: Invalid query parameters '403': content: application/json: schema: $ref: >- #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailForbidden description: Access denied '500': content: application/json: schema: $ref: >- #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailInternalError description: Internal server error components: schemas: internal_agents.ListAgentsResponse: properties: items: items: $ref: '#/components/schemas/internal_agents.AgentItem' type: array nextCursor: example: 507f1f77bcf86cd799439011 type: string previousCursor: example: 507f1f77bcf86cd799439011 type: string total: example: 1 type: integer type: object github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailBadRequest: properties: detail: example: request body validation failed type: string errors: items: $ref: >- #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.FieldError type: array instance: example: /v1/{resource} type: string status: example: 400 type: integer title: example: Bad Request type: string traceId: example: api--a4d2f126-bec4-4544-a049-7c0cf08524ed type: string type: example: about:blank type: string type: object github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailForbidden: properties: detail: example: 'access denied: insufficient permissions' type: string instance: example: /v1/{resource}/{id} type: string status: example: 403 type: integer title: example: Forbidden type: string traceId: example: api--a4d2f126-bec4-4544-a049-7c0cf08524ed type: string type: example: about:blank type: string type: object github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailInternalError: properties: detail: example: internal server error type: string instance: example: /v1/{resource} type: string status: example: 500 type: integer title: example: Internal Server Error type: string traceId: example: api--a4d2f126-bec4-4544-a049-7c0cf08524ed type: string type: example: about:blank type: string type: object internal_agents.AgentItem: properties: agentType: description: >- AgentType is the modality the agent was authored for. Always present: an agent stored without one — every agent that predates the field — reads back as "text", because it was authored when chat was the only thing an agent could be. enum: - text - voice example: voice type: string createdAt: type: integer createdBy: example: 507f1f77bcf86cd799439011 type: string description: type: string disabledToolReferenceIds: items: type: string type: array guardrails: $ref: '#/components/schemas/internal_agents.GuardrailsResponse' hooks: $ref: '#/components/schemas/internal_agents.HooksResponse' id: example: 507f1f77bcf86cd799439011 type: string image: type: string imageOptimizedFormat: type: boolean instructions: type: string knowledge: $ref: '#/components/schemas/internal_agents.KnowledgeResponse' largeLanguageModelReferenceId: type: string lastChangedAt: type: integer lastChangedBy: example: 507f1f77bcf86cd799439011 type: string llmConfig: $ref: '#/components/schemas/internal_agents.LLMConfigResponse' localeReferenceId: type: string name: type: string organisationId: example: 507f1f77bcf86cd799439011 type: string personaReferenceId: type: string projectId: example: 507f1f77bcf86cd799439011 type: string referenceId: type: string role: type: string skillReferenceIds: items: type: string type: array toolReferenceIds: items: type: string type: array voiceLargeLanguageModelReferenceId: description: >- VoiceLargeLanguageModelReferenceId links a realtime (V2V) LLM for voice sessions. Optional UUID; text turns never use it. type: string type: object github_com_cognigy_ai-agents-v2_internal_middleware.FieldError: properties: field: type: string message: type: string type: object internal_agents.GuardrailsResponse: properties: dataPrivacy: $ref: '#/components/schemas/internal_agents.DataPrivacyResponse' safetySettings: $ref: '#/components/schemas/internal_agents.SafetySettingsResponse' type: object internal_agents.HooksResponse: properties: preTurn: items: $ref: '#/components/schemas/internal_agents.PreTurnHook' type: array type: object internal_agents.KnowledgeResponse: properties: cognigyParameters: $ref: '#/components/schemas/internal_agents.CognigyRAGParametersDTO' context: type: string onSearchFailure: type: string ragMode: type: string ragType: type: string type: object internal_agents.LLMConfigResponse: properties: maxOutputTokens: type: integer reasoningEffort: type: string temperature: type: number type: object internal_agents.DataPrivacyResponse: properties: contactProfilesOption: example: completeProfile type: string selectedProfileFields: items: type: string type: array type: object internal_agents.SafetySettingsResponse: properties: avoidCopyrightInfringements: type: boolean avoidHarmfulContent: type: boolean avoidUngroundedContent: type: boolean preventJailbreakAndManipulation: type: boolean type: object internal_agents.PreTurnHook: properties: handler: $ref: '#/components/schemas/internal_agents.HookHandler' type: object internal_agents.CognigyRAGParametersDTO: properties: language: type: string stores: items: type: string type: array topK: type: integer type: object internal_agents.HookHandler: properties: flowReferenceId: type: string kind: type: string type: object securitySchemes: ApiKey: description: '[Production] API key for production authentication' in: header name: X-API-Key type: apiKey ````