openapi: 3.0.4 info: title: Evolution Foundation - Evolution API - Instance description: Main Evolution API for WhatsApp version: 2.3.7 servers: - url: http://localhost:8080 description: Local development server - url: https://api.evolution-api.com description: Production server - url: '{customUrl}' description: Custom server variables: customUrl: default: https://your-instance.com description: Enter your server URL security: - ApiKeyAuth: [] paths: /instance/connect/{instanceName}: get: summary: Connect Instance description: Connect instance to WhatsApp parameters: - $ref: '#/components/parameters/InstanceName' responses: '200': description: Connection initiated content: application/json: schema: $ref: '#/components/schemas/ConnectInstanceResponse' '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: BAD_REQUEST message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/connect/{instanceName} method: GET '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: UNAUTHORIZED message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/connect/{instanceName} method: GET '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: FORBIDDEN message: Insufficient permissions to perform this action meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/connect/{instanceName} method: GET '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: NOT_FOUND message: Instance not found meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/connect/{instanceName} method: GET '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/connect/{instanceName} method: GET /instance/connectionState/{instanceName}: get: summary: Get Connection State description: Get current connection state of instance parameters: - $ref: '#/components/parameters/InstanceName' responses: '200': description: Connection state retrieved content: application/json: schema: type: object properties: instance: type: object properties: instanceName: type: string example: sua-instancia state: type: string enum: - open - close - connecting example: close '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: BAD_REQUEST message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/connectionState/{instanceName} method: GET '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: UNAUTHORIZED message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/connectionState/{instanceName} method: GET '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: FORBIDDEN message: Insufficient permissions to perform this action meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/connectionState/{instanceName} method: GET '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: NOT_FOUND message: Instance not found meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/connectionState/{instanceName} method: GET '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/connectionState/{instanceName} method: GET /instance/create: post: summary: Create Instance description: Create a new WhatsApp instance requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InstanceCreate' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/InstanceCreateResponse' '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: BAD_REQUEST message: Invalid input data meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/create method: POST '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: UNAUTHORIZED message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/create method: POST '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: FORBIDDEN message: Insufficient permissions to perform this action meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/create method: POST '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: NOT_FOUND message: Resource not found meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/create method: POST '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/create method: POST /instance/delete/{instanceName}: delete: summary: Delete Instance description: Delete an instance parameters: - $ref: '#/components/parameters/InstanceName' responses: '200': description: Instance deleted content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Instance deleted successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: BAD_REQUEST message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/delete/{instanceName} method: DELETE '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: UNAUTHORIZED message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/delete/{instanceName} method: DELETE '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: FORBIDDEN message: Insufficient permissions to perform this action meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/delete/{instanceName} method: DELETE '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: NOT_FOUND message: Instance not found meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/delete/{instanceName} method: DELETE '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/delete/{instanceName} method: DELETE /instance/fetchInstances: get: summary: Fetch All Instances description: Get list of all instances responses: '200': description: List of instances content: application/json: schema: type: array items: $ref: '#/components/schemas/InstanceResponse' '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: BAD_REQUEST message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/fetchInstances method: GET '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: UNAUTHORIZED message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/fetchInstances method: GET '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: FORBIDDEN message: Insufficient permissions to perform this action meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/fetchInstances method: GET '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: NOT_FOUND message: Resource not found meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/fetchInstances method: GET '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/fetchInstances method: GET /instance/logout/{instanceName}: delete: summary: Logout Instance description: Logout and disconnect instance parameters: - $ref: '#/components/parameters/InstanceName' responses: '200': description: Instance logged out content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Instance logged out successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: BAD_REQUEST message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/logout/{instanceName} method: DELETE '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: UNAUTHORIZED message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/logout/{instanceName} method: DELETE '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: FORBIDDEN message: Insufficient permissions to perform this action meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/logout/{instanceName} method: DELETE '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: NOT_FOUND message: Instance not found meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/logout/{instanceName} method: DELETE '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/logout/{instanceName} method: DELETE /instance/restart/{instanceName}: post: summary: Restart Instance description: Restart a WhatsApp instance parameters: - $ref: '#/components/parameters/InstanceName' responses: '200': description: Instance restarted. Returns error status with message. content: application/json: schema: type: object properties: error: type: boolean message: type: string example: error: true message: '#error-details' '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: BAD_REQUEST message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/restart/{instanceName} method: POST '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: UNAUTHORIZED message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/restart/{instanceName} method: POST '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: FORBIDDEN message: Insufficient permissions to perform this action meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/restart/{instanceName} method: POST '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: NOT_FOUND message: Instance not found meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/restart/{instanceName} method: POST '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/restart/{instanceName} method: POST /instance/setPresence/{instanceName}: post: summary: Set Presence description: Set instance presence status parameters: - $ref: '#/components/parameters/InstanceName' requestBody: required: true content: application/json: schema: type: object required: - presence properties: presence: type: string enum: - available - unavailable - composing - recording responses: '200': description: Presence updated content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Presence updated successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: BAD_REQUEST message: Invalid input data meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/setPresence/{instanceName} method: POST '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: UNAUTHORIZED message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/setPresence/{instanceName} method: POST '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: FORBIDDEN message: Insufficient permissions to perform this action meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/setPresence/{instanceName} method: POST '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: NOT_FOUND message: Instance not found meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/setPresence/{instanceName} method: POST '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /instance/setPresence/{instanceName} method: POST components: schemas: ErrorResponse: type: object required: - success - error properties: success: type: boolean example: false error: type: object required: - code - message properties: code: type: string message: type: string meta: type: object properties: timestamp: type: string format: date-time path: type: string method: type: string InstanceCreate: type: object required: - instanceName properties: instanceName: type: string qrcode: type: boolean default: true integration: type: string token: type: string number: type: string webhook: type: object properties: enabled: type: boolean url: type: string events: type: array items: type: string ConnectInstanceResponse: type: object properties: pairingCode: type: string nullable: true example: null code: type: string example: 2@exemple base64: type: string example: data:image/png;base64,exemple count: type: integer example: 1 InstanceResponse: type: object properties: instance: type: object properties: instanceName: type: string status: type: string qrcode: type: object nullable: true connectionStatus: type: object InstanceCreateResponse: type: object properties: instance: type: object properties: instanceName: type: string example: sua-instancia instanceId: type: string example: exemple-instance-id integration: type: string example: WHATSAPP-BAILEYS webhookWaBusiness: type: string nullable: true example: null accessTokenWaBusiness: type: string example: '' status: type: string example: connecting hash: type: string example: exemple-hash webhook: type: object websocket: type: object rabbitmq: type: object nats: type: object sqs: type: object settings: type: object properties: rejectCall: type: boolean example: false msgCall: type: string example: '' groupsIgnore: type: boolean example: false alwaysOnline: type: boolean example: false readMessages: type: boolean example: false readStatus: type: boolean example: false syncFullHistory: type: boolean example: false wavoipToken: type: string example: '' qrcode: type: object properties: pairingCode: type: string nullable: true example: null code: type: string example: 2@exemple base64: type: string example: data:image/png;base64,exemple count: type: integer example: 1 securitySchemes: ApiKeyAuth: type: apiKey in: header name: apikey description: API Key for authentication (global or instance-specific) parameters: InstanceName: name: instanceName in: path required: true description: WhatsApp instance name schema: type: string example: my-instance