sendraven-ai Conversion Goals API

openapi: 3.2.0
info:
  title: Sendraven Ai Conversion Goals API
  version: 1.0.0
  description: 'Operations tagged Conversion Goals across 2 of this provider''s published API definitions: sendraven-ai-api-openapi.json, sendraven-ai-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.sendraven.ai
security:
- bearerAuth: []
tags:
- name: Conversion Goals
paths:
  /v1/conversion-goals:
    get:
      summary: List conversion goals
      description: Every event name the workspace counts as a conversion, oldest first. Not paged (a workspace has at most 50).
      x-required-scope: broadcasts:read
      responses:
        '200':
          description: Goals.
          content:
            application/json:
              schema:
                type: object
                required:
                - object
                - data
                - has_more
                - next_cursor
                properties:
                  object:
                    type: string
                    enum:
                    - list
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConversionGoal'
                  has_more:
                    type: boolean
                    description: 'Not paged: true only when the list hit its cap, meaning there is more than this endpoint can return.'
                  next_cursor:
                    type:
                    - string
                    - 'null'
                    description: Always null; this list is not paged.
        '401':
          description: 'unauthorized: no Bearer token, or the key or token is invalid, revoked or expired.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'forbidden: the key lacks the broadcasts:read scope. The message names it.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'rate_limited: more requests than the per-key rate (600 a minute by default). Wait the seconds in the Retry-After header and retry.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 'service_unavailable: the API is under heavy load and could not get a database connection in time. Usually nothing was done; a send that was already under way may have been, so check GET /v1/emails before retrying one. Wait the seconds in the Retry-After header.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Conversion Goals
      operationId: getV1ConversionGoals
      x-operation-id-source: derived
    post:
      summary: Create a conversion goal
      description: 'From now on, an event sent to POST /v1/events with this name is also a conversion, credited to the last email the person clicked within window_days (default 7). Events received before the goal existed are not counted. Only clicks by a person count: security scanners are excluded, and opens never earn credit.'
      x-required-scope: broadcasts:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - event_name
              additionalProperties: false
              properties:
                event_name:
                  type: string
                  minLength: 1
                  maxLength: 120
                  description: Matched exactly, case-sensitive.
                window_days:
                  type: integer
                  minimum: 1
                  maximum: 30
                  default: 7
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionGoal'
        '400':
          description: 'invalid_json: the request body is not valid JSON.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 'unauthorized: no Bearer token, or the key or token is invalid, revoked or expired.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'forbidden: the key lacks the broadcasts:write scope. The message names it.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 'conflict: this event name is already a goal. GET /v1/conversion-goals lists it with its id. Also idempotency_in_progress: a request with the same Idempotency-Key was still running on this path after waiting up to 8 seconds for it (a retry that finds it finished receives its response instead). Retry after a short wait.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: 'payload_too_large: the body is larger than this endpoint accepts (5 MB unless stated).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: 'invalid_request: the body failed validation, or the workspace already has 50 goals. Also idempotency_key_reused: this Idempotency-Key was already used on this path with a different request body (checked right after the scope, so a credential without the scope gets 403 instead, and answered at once even while the first request is still running). Do not retry; send the new request under a new key.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'rate_limited: more requests than the per-key rate (600 a minute by default). Wait the seconds in the Retry-After header and retry.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 'service_unavailable: the API is under heavy load and could not get a database connection in time. Usually nothing was done; a send that was already under way may have been, so check GET /v1/emails before retrying one. Wait the seconds in the Retry-After header.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: Idempotency-Key
        in: header
        schema:
          type: string
        description: 'Replaying the same key on the same path in this workspace within 24 hours returns the stored response, with an Idempotent-Replay: true header, instead of acting again. Only successful responses are stored, so a failed request can be fixed and retried under the same key. The body is compared (key order ignored): the same key with a different body is 422 idempotency_key_reused, so use a new key for every new request. Use an unguessable value such as a UUID.'
      tags:
      - Conversion Goals
      operationId: postV1ConversionGoals
      x-operation-id-source: derived
    servers:
    - url: https://api.sendraven.ai
  /v1/conversion-goals/{id}:
    get:
      summary: Retrieve a conversion goal
      x-required-scope: broadcasts:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: The goal's id from GET /v1/conversion-goals (a UUID), not its event name.
      responses:
        '200':
          description: The goal.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionGoal'
        '401':
          description: 'unauthorized: no Bearer token, or the key or token is invalid, revoked or expired.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'forbidden: the key lacks the broadcasts:read scope. The message names it.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'not_found: no goal with this id in the workspace.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'rate_limited: more requests than the per-key rate (600 a minute by default). Wait the seconds in the Retry-After header and retry.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 'service_unavailable: the API is under heavy load and could not get a database connection in time. Usually nothing was done; a send that was already under way may have been, so check GET /v1/emails before retrying one. Wait the seconds in the Retry-After header.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Conversion Goals
      operationId: getV1ConversionGoalsById
      x-operation-id-source: derived
    patch:
      summary: Change a goal's window
      description: The new window applies to conversions not yet attributed. One already credited keeps its message, so a report never moves under a reader. The event name cannot change; create a new goal instead.
      x-required-scope: broadcasts:write
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: The goal's id from GET /v1/conversion-goals (a UUID), not its event name.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - window_days
              additionalProperties: false
              properties:
                window_days:
                  type: integer
                  minimum: 1
                  maximum: 30
      responses:
        '200':
          description: The updated goal.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionGoal'
        '400':
          description: 'invalid_json: the request body is not valid JSON.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 'unauthorized: no Bearer token, or the key or token is invalid, revoked or expired.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'forbidden: the key lacks the broadcasts:write scope. The message names it.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'not_found: no goal with this id in the workspace.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: 'payload_too_large: the body is larger than this endpoint accepts (5 MB unless stated).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: 'invalid_request: window_days is missing or out of range, or another field was sent.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'rate_limited: more requests than the per-key rate (600 a minute by default). Wait the seconds in the Retry-After header and retry.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 'service_unavailable: the API is under heavy load and could not get a database connection in time. Usually nothing was done; a send that was already under way may have been, so check GET /v1/emails before retrying one. Wait the seconds in the Retry-After header.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Conversion Goals
      operationId: patchV1ConversionGoalsById
      x-operation-id-source: derived
    delete:
      summary: Delete a conversion goal
      description: Deletes the goal and every conversion recorded against it; they cannot be restored. The event name keeps working as an ordinary event, and automations it starts are unaffected.
      x-required-scope: broadcasts:write
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: The goal's id from GET /v1/conversion-goals (a UUID), not its event name.
      responses:
        '200':
          description: Deleted.
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - deleted
                - conversions_deleted
                properties:
                  id:
                    type: string
                  deleted:
                    type: boolean
                    enum:
                    - true
                  conversions_deleted:
                    type: integer
                    minimum: 0
        '401':
          description: 'unauthorized: no Bearer token, or the key or token is invalid, revoked or expired.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'forbidden: the key lacks the broadcasts:write scope. The message names it.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'not_found: no goal with this id in the workspace.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'rate_limited: more requests than the per-key rate (600 a minute by default). Wait the seconds in the Retry-After header and retry.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 'service_unavailable: the API is under heavy load and could not get a database connection in time. Usually nothing was done; a send that was already under way may have been, so check GET /v1/emails before retrying one. Wait the seconds in the Retry-After header.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Conversion Goals
      operationId: deleteV1ConversionGoalsById
      x-operation-id-source: derived
    servers:
    - url: https://api.sendraven.ai
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - type
          - message
          properties:
            type:
              type: string
              description: 'Stable and safe to branch on, and the same status on every route: invalid_request (422), invalid_json (400), payload_too_large (413), unauthorized (401), forbidden (403), not_found (404), conflict (409, an identifier already taken), invalid_state (409, the resource''s current state does not allow this), plan_limit_reached (402), payment_method_required (402), billing_past_due (402), budget_exceeded (402), no_verified_identity (422), missing_variables (422), unknown_topic (422), idempotency_in_progress (409), idempotency_key_reused (422), approval_in_progress (409), rate_limited (429), daily_limit (429), recipient_not_allowed (403), invalid_schedule (422), warmup_limit (422), no_postal_address (422), workspace_suspended (422), gone (410), ses_error (502), internal_error (500), service_unavailable (503).'
            message:
              type: string
              description: For people; may change.
            details:
              type: array
              items:
                type: object
                additionalProperties: true
              description: 'On many 422 invalid_request answers: one entry per field that failed validation.'
            missing:
              type: array
              items:
                type: string
              description: 'Only on missing_variables, and always there: the names of the template variables that were not supplied.'
    ConversionGoal:
      type: object
      required:
      - id
      - event_name
      - window_days
      - created_at
      properties:
        id:
          type: string
          format: uuid
        event_name:
          type: string
          description: The event name, matched exactly against name on POST /v1/events. Unique within the workspace.
        window_days:
          type: integer
          minimum: 1
          maximum: 30
          description: How many days before the conversion a click may be and still earn the credit.
        created_at:
          type: string
          format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API key of the form sk_live_…, created at /developers, or an OAuth access token (srv_oat_…). An OAuth token carries its grant's scopes but none of an API key's guardrails, and cannot decide approvals.
x-refined-from:
- sendraven-ai-api-openapi.json
- sendraven-ai-openapi.json