> ## Documentation Index > Fetch the complete documentation index at: https://developer.communicate.so/llms.txt > Use this file to discover all available pages before exploring further. # Read an accessible agent and its settings > Use an explicitly scoped user-bound account bearer credential or an application session. Scope grants are intersected with live membership, role, tenant isolation, agent access and plan limits; a credential does not grant an owner role. Invitation acceptance requires the verified recipient email. ## OpenAPI ````yaml https://app.communicate.so/api/v1/openapi/mintlify.json get /workspaces/{workspaceId}/agents/{agentId} openapi: 3.1.0 info: title: Communicate Public REST API version: 1.1.0 summary: >- Scoped agent chat, account credential lifecycle and workspace bootstrap operations. description: >- Canonical external schema for implemented REST operations. Account credentials and application sessions authorize the documented account and workspace operations separately from workspace keys. Exchange a workspace API-key client ID and secret for a short-lived OAuth access token, or use the `ck_` key directly for backward compatibility. `requestId` is optional but, when supplied, becomes the idempotency key for retries of the same chat input. servers: - url: https://app.communicate.so/api/v1 description: Canonical external base URL served through the Next.js /api/v1 rewrite. security: - oauth2: [] - bearerAuth: [] paths: /workspaces/{workspaceId}/agents/{agentId}: get: tags: - Agents summary: Read an accessible agent and its settings description: >- Use an explicitly scoped user-bound account bearer credential or an application session. Scope grants are intersected with live membership, role, tenant isolation, agent access and plan limits; a credential does not grant an owner role. Invitation acceptance requires the verified recipient email. operationId: readAgent parameters: - name: workspaceId in: path required: true schema: type: string minLength: 1 - name: agentId in: path required: true schema: type: string minLength: 1 responses: '200': description: Read an accessible agent and its settings content: application/json: schema: $ref: '#/components/schemas/readAgentResponse' '401': description: >- Missing, invalid, expired or revoked account credential or application session. '402': description: Plan entitlement, capacity or credits do not allow this operation. '403': description: >- Required account scope, live verified identity, membership or role permission is missing. '404': description: Workspace or addressed resource is not visible to this member. '409': description: >- Support handle, source URL or pending transfer conflicts with this operation. '422': description: Website URL or extraction source is not supported. '429': description: Agent request or website crawl rate limit exceeded. '500': description: Unexpected server failure. '503': description: Authorization service temporarily unavailable. security: - accountBearer: [] - accountSession: [] - localAccountSession: [] components: schemas: readAgentResponse: type: object properties: id: type: string minLength: 1 workspaceId: type: string minLength: 1 name: type: string systemPrompt: anyOf: - type: string - type: 'null' status: type: string enum: - active - inactive - draft inTransfer: type: boolean model: type: string temperature: type: number rateLimitPerMinute: type: integer minimum: -9007199254740991 maximum: 9007199254740991 allowedDomains: type: array items: type: string widgetConfig: type: object properties: accentColor: type: string pattern: ^#[0-9a-fA-F]{6}$ displayName: type: string maxLength: 60 greeting: type: string maxLength: 500 suggestedPrompts: maxItems: 6 type: array items: type: string minLength: 1 maxLength: 120 promptGroups: maxItems: 4 type: array items: type: object properties: title: type: string minLength: 1 maxLength: 80 prompts: minItems: 1 maxItems: 6 type: array items: type: string minLength: 1 maxLength: 120 required: - title - prompts additionalProperties: false labels: type: object properties: locale: type: string enum: - en - es - fr - de - pt composerPlaceholder: type: string maxLength: 120 sendButton: type: string maxLength: 40 openButton: type: string maxLength: 80 poweredBy: type: string maxLength: 80 additionalProperties: false messagePlaceholder: type: string maxLength: 120 privacyPolicyUrl: format: uri description: A URL with HTTP or HTTPS protocol. type: string maxLength: 500 dictationEnabled: type: boolean showPoweredBy: type: boolean bubblePosition: type: string enum: - right - left socialLinks: maxItems: 8 type: array items: type: object properties: label: type: string minLength: 1 maxLength: 40 url: format: uri description: A URL with HTTP or HTTPS protocol. type: string maxLength: 500 required: - label - url additionalProperties: false showSupportEmail: type: boolean chatPageTheme: type: string enum: - light - dark - both widgetEnabled: type: boolean additionalProperties: false notifyConfig: type: object properties: email: type: string maxLength: 254 format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ onNewConversation: type: boolean additionalProperties: false voiceConfig: allOf: - if: properties: enabled: const: true required: - enabled then: required: - voiceId type: object properties: enabled: type: boolean voiceId: type: string minLength: 1 maxLength: 200 language: type: string maxLength: 12 pattern: ^[a-z]{2,3}(?:-[A-Z]{2})?$ consentCopy: type: string minLength: 1 maxLength: 1000 maxDurationSeconds: type: integer minimum: 30 maximum: 3600 required: - enabled - language - consentCopy - maxDurationSeconds additionalProperties: false learningConfig: type: object properties: captureEnabled: type: boolean additionalProperties: false escalationTeamId: anyOf: - type: string minLength: 1 - type: 'null' supportEmail: anyOf: - type: string - type: 'null' website: anyOf: - type: string - type: 'null' logoUrl: anyOf: - type: string - type: 'null' chatPageEnabled: type: boolean chatPageBlockedAt: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ - type: 'null' indexable: type: boolean emailFromName: anyOf: - type: string - type: 'null' deletionScheduledAt: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ - type: 'null' deletionRequestedBy: anyOf: - type: string minLength: 1 - type: 'null' createdAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ updatedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ required: - id - workspaceId - name - systemPrompt - status - inTransfer - model - temperature - rateLimitPerMinute - allowedDomains - widgetConfig - notifyConfig - voiceConfig - learningConfig - escalationTeamId - supportEmail - website - logoUrl - chatPageEnabled - chatPageBlockedAt - indexable - emailFromName - deletionScheduledAt - deletionRequestedBy - createdAt - updatedAt additionalProperties: false securitySchemes: oauth2: type: oauth2 description: >- OAuth 2.0 client-credentials tokens bounded by the source API key scope ceiling. flows: clientCredentials: tokenUrl: https://app.communicate.so/api/v1/oauth/token scopes: agents:read: List agents in the authenticated workspace. chat:write: Create chat turns with an agent in the authenticated workspace. bearerAuth: type: http scheme: bearer bearerFormat: API key description: Workspace API key token with the `ck_` prefix. accountBearer: type: http scheme: bearer bearerFormat: Account credential description: >- Opaque user-bound `ca_` account credential. Each request checks live account scopes, verified email, expiry, revocation and the issuer session. Not a workspace `ck_` key or OAuth access token. accountSession: type: apiKey in: cookie name: __Secure-better-auth.session_token description: >- Signed Better Auth session cookie for an HTTPS application origin. Credential management additionally requires verified email and fresh password proof on writes. localAccountSession: type: apiKey in: cookie name: better-auth.session_token description: >- Signed session cookie used when the configured application auth origin is HTTP, such as local development. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.