Elocuenti Audit API

openapi: 3.2.0
info:
  title: Elocuenti Audit API
  version: 1.0.0
  description: 'The public REST API of Elocuenti: contacts, conversations, funnels, WhatsApp templates, knowledge base, automations, events, AI calls, webhooks and charges (Colombia).


    Authenticate every request with `Authorization: Bearer `. A key that starts with `eloc_live_` acts in production; one that starts with `eloc_sand_` is a sandbox key: it never messages or calls your customers, and the **Sandbox** line of each operation says what it does instead. Create keys in Settings → API Keys.


    Guides and reference: https://www.elocuenti.com/api/docs'
servers:
- url: https://www.elocuenti.com
tags:
- name: Audit
paths:
  /api/v1/requests/{request_id}:
    get:
      tags:
      - Audit
      summary: See how one of your calls went
      description: 'Returns what the API recorded about one of your calls: the operation, the HTTP status, the error `code` if any, how long it took and when it arrived. Use it when you only kept the `request_id`: every answer carries it, in the body and in the `X-Request-Id` header.


        It only shows calls made with the same key, for 90 days: a call of another key (even one of your business), an older one, an unknown id or the call in progress answer `404`. A call usually shows up within 10 seconds, so a `404` right after it is solved by asking again a little later. If you send your own `X-Request-Id` and repeat it, the most recent call answers. The body you sent, your IP address and the key''s secret are never part of the answer. Your team sees the activity of every key in Settings → API Keys → Activity.


        **Permission:** any valid key · **Sandbox:** reads the key''s own environment'
      operationId: get_request
      security:
      - ApiKey: []
      x-access:
        permission: none
        sandbox: readsOwnEnvironment
      parameters:
      - name: request_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[\w.:-]{1,128}$
          description: 'The `request_id` of the call you want to look up: it comes back in the body of every answer and in the `X-Request-Id` header.'
          examples:
          - 3f9a1c07d2b4
          title: Request Id
        description: 'The `request_id` of the call you want to look up: it comes back in the body of every answer and in the `X-Request-Id` header.'
      responses:
        '200':
          description: How the call went.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestRecordResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  responses:
    Forbidden:
      description: 'The API key is valid but cannot do this.


        - `forbidden`: The API key does not have the permission this operation needs. Create a new key with the permission the operation documents: the permissions of a key are set when it is created.

        - `legacy_key_not_allowed`: This operation is not available to the original business key (the one that starts with `eloq_` or `elocuenti_`). Create an API key in Settings → API Keys (it starts with `eloc_live_` or `eloc_sand_`) and use it.

        - `creator_cannot_attend_conversations`: The team that attends conversations is not shown to this key, because the person who created it does not attend conversations. Read the team with a key created by an owner or an administrator.

        - `sandbox_not_supported`: This operation is not available with a sandbox key. Use a production key (`eloc_live_`), or check the operation''s page to see how it behaves in sandbox.

        - `webhook_content_not_allowed`: Receiving the text of the messages needs a key with the `conversations:read` permission that was created by an owner or an administrator. The text of every message of the business would reach your address, so it is limited to who can read all the conversations. Create the subscription (or change it) with a key made by an owner or an administrator that holds `conversations:read`, or leave `include_message_content` off and read each message with the API.

        - `calls_not_available`: The business''s plan or billing status does not allow outbound calls. Nothing was dialed. Check the plan and the billing status in the dashboard (for example, a trial does not include voice calls).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: 'The resource was not found.


        - `not_found`: The resource does not exist, or it is not available to this API key. Check the identifier. If the resource has a list operation, use it to get valid identifiers.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: 'Too many requests.


        - `whatsapp_rate_limited`: WhatsApp is limiting how fast the business can create or delete templates. Wait a few minutes and try again with the same Idempotency-Key. WhatsApp allows a limited number of new templates per hour.

        - `call_capacity_reached`: All the business''s phone lines for AI calls are busy right now. Nothing was dialed. Wait the seconds in the `Retry-After` header and send the request again; some lines are always kept free for your team''s own calls.

        - `rate_limit_exceeded`: Too many requests: the limit was reached. Wait the seconds in the `Retry-After` header and try again. Your key''s limits are in `GET /api/v1/me`.

        - `daily_limit_exceeded`: This API key reached the number of changes it can make in a day for this operation. Nothing was changed. Send only what changed since your last sync, or wait until tomorrow; the day''s limit is in the operation''s page.'
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: 'Something went wrong on our side.


        - `internal_error`: An unexpected error happened on our side. Do not blindly repeat a write: check whether it was applied, or repeat it with the same Idempotency-Key. If it keeps failing, write to us with the `request_id`.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceUnavailable:
      description: 'The service could not complete the request.


        - `temporary_conflict`: The request collided with another change made at the same moment and was not applied. Send it again right away: nothing was changed, so repeating it is safe.

        - `outcome_unknown`: We could not confirm whether the operation was completed. If the operation accepts an Idempotency-Key, repeat it with the same key: if it was already applied, you will get the same result. If it does not accept one, check the state before repeating it.

        - `service_unavailable`: The service cannot answer right now. Try again in a few seconds. If it persists, write to us at contacto@elocuenti.com with the `request_id` of the answer.'
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: 'The API key was not accepted.


        - `missing_api_key`: The request has no API key. Send it in the Authorization header: `Authorization: Bearer <your key>`.

        - `invalid_api_key`: The API key is not recognized. Check that it is complete and was copied correctly. If it still fails, create a new one in Settings → API Keys.

        - `api_key_expired`: The API key has expired. Create a new key in Settings → API Keys and use it instead.

        - `api_key_inactive`: The API key was revoked. Create a new key in Settings → API Keys and use it instead.

        - `api_key_owner_inactive`: The person who created this key is no longer active in the business. Ask an owner or administrator to transfer it to another person in Settings → API Keys, or create a new one.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  headers:
    X-RateLimit-Reset:
      description: 'The moment that window ends, as a Unix timestamp (seconds since 1970-01-01 UTC). It is not the seconds to wait: for that, use `Retry-After`.'
      schema:
        type: integer
    X-RateLimit-Limit:
      description: How many requests the key may make in the window that applies to this answer.
      schema:
        type: integer
    Retry-After:
      description: 'When the answer asks you to wait (a rate limit, a request still being processed, a temporary failure): how many seconds to wait before sending the request again.'
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: How many requests are left in that window.
      schema:
        type: integer
    X-Request-Id:
      description: The identifier of this request, also in the body as `request_id`. Send your own `X-Request-Id` (up to 128 letters, digits, `.`, `_`, `:` or `-`) and it comes back unchanged, so you can match your logs with ours.
      schema:
        type: string
  schemas:
    RequestRecordResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/RequestRecord'
        request_id:
          type: string
          description: The identifier of this request. Give it to support if you need help.
          examples:
          - 3f9a1c07d2b4
          title: Request Id
      required:
      - data
      - request_id
      title: RequestRecordResponse
    FieldIssue:
      type: object
      properties:
        field:
          type: string
          description: 'The field that failed: its name, or a dotted path for a nested one (`items.0.name`).'
          examples:
          - name
          title: Field
        issue:
          type: string
          description: 'What is wrong with it: `required`, `invalid_type`, `invalid_format`, `too_small`, `too_big`, `invalid_value` or `unrecognized_field`. An operation that refers to another resource by id can also say `not_found` (that id does not exist in your business) or a reason specific to it, which its page explains. It never repeats the value you sent.'
          examples:
          - required
          title: Issue
      required:
      - field
      - issue
      description: One field that did not pass validation.
      title: FieldIssue
    RequestRecord:
      type: object
      properties:
        request_id:
          type: string
          description: 'The identifier of the call: the one you asked for.'
          examples:
          - 3f9a1c07d2b4
          title: Request Id
        method:
          type: string
          description: The HTTP method of the call.
          examples:
          - POST
          title: Method
        path:
          type: string
          description: 'The operation that was called, as the reference writes it, with the ids as `{placeholders}`: the ids you sent are not repeated.'
          examples:
          - /api/v1/contacts/{id}
          title: Path
        status:
          type: integer
          description: The HTTP status the API answered.
          examples:
          - 422
          title: Status
        code:
          anyOf:
          - type: string
          - type: 'null'
          examples:
          - invalid_request
          description: The `code` of the error the API answered, or `null` if the call went well. Every code is explained in the error guide.
          title: Code
        latency_ms:
          type: integer
          description: How long the API took to answer, in milliseconds.
          examples:
          - 37
          title: Latency Ms
        created_at:
          type: string
          description: When the call was received (UTC, ISO 8601).
          examples:
          - '2026-10-28T15:04:05.000Z'
          title: Created At
      required:
      - request_id
      - method
      - path
      - status
      - code
      - latency_ms
      - created_at
      description: How one call to the API went.
      title: RequestRecord
    Error:
      type: object
      properties:
        error:
          type: string
          description: What happened and what to do about it, in English or Spanish (it follows the `Accept-Language` header). Meant for a person; do not parse it.
          examples:
          - The API key has expired. Create a new key in Settings → API Keys and use it instead.
          title: Error
        code:
          type: string
          enum:
          - missing_api_key
          - invalid_api_key
          - api_key_expired
          - api_key_inactive
          - forbidden
          - legacy_key_not_allowed
          - creator_cannot_attend_conversations
          - api_key_owner_inactive
          - sandbox_not_supported
          - not_found
          - media_expired
          - media_not_ready
          - conflict
          - template_name_taken
          - template_being_created
          - template_content_rejected
          - template_limit_reached
          - whatsapp_not_connected
          - whatsapp_connection_unavailable
          - whatsapp_rate_limited
          - webhook_limit_reached
          - rotation_in_progress
          - webhook_url_taken
          - webhook_content_not_allowed
          - webhook_inactive
          - contact_cannot_be_called
          - call_outside_window
          - calls_not_available
          - phone_line_unavailable
          - call_capacity_reached
          - call_in_progress
          - call_not_placed
          - request_in_progress
          - idempotency_key_reused
          - invalid_json
          - invalid_request
          - payload_too_large
          - rate_limit_exceeded
          - daily_limit_exceeded
          - temporary_conflict
          - outcome_unknown
          - service_unavailable
          - internal_error
          description: A stable identifier of the error. Branch on this, not on `error`. Every code is explained in the error guide.
          examples:
          - api_key_expired
          title: Code
        request_id:
          type: string
          description: The identifier of this request. Give it to support if you need help.
          examples:
          - 3f9a1c07d2b4
          title: Request Id
        details:
          description: 'On `invalid_request`: one entry per field that failed. A `404` or `409` that blames one field of your request (for example, an id that does not exist) names it here too.'
          type: array
          items:
            $ref: '#/components/schemas/FieldIssue'
          title: Details
        doc_url:
          type: string
          description: The section of the error guide that explains this code.
          examples:
          - https://www.elocuenti.com/api/docs/errors#api_key_expired
          title: Doc Url
      required:
      - error
      - code
      - request_id
      - doc_url
      description: The body of an error answer.
      title: Error
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: API key