openapi.yaml

openapi: 3.0.0
info:
  contact:
    email: dev@approveapi.com
  description: The simple API to request a user's approval on anything via email + sms.
  title: ApproveAPISwagger
  version: 1.0.1
servers:
- url: https://approve.sh
paths:
  /prompt:
    post:
      description: Creates a prompt and pushes it to the user (sends via email, sms, or other supported protocols).
      operationId: CreatePrompt
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePromptRequest'
        required: true
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prompt'
          description: OK
        400:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Invalid parameters
        401:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Missing or invalid API key in the username basic auth field
        504:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Polling timed out with no user response
      security:
      - apiKey: []
      summary: Sending a prompt
      tags:
      - approve
  /prompt/{id}:
    get:
      description: Retrieve the prompt object with the given ID.
      operationId: GetPrompt
      parameters:
      - description: The identifier for a pending or completed prompt. This is returned when you create a prompt.
        explode: false
        in: path
        name: id
        required: true
        schema:
          type: string
        style: simple
      - description: If true, the request waits (long-polls) until the user responds to the prompt or more than 10 minutes pass. Defaults to false.
        explode: true
        in: query
        name: long_poll
        required: false
        schema:
          type: boolean
        style: form
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prompt'
          description: OK
        400:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Invalid parameters
        404:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: A prompt with this identifier could not be found
      security:
      - apiKey: []
      summary: Retrieve a prompt
      tags:
      - approve
  /prompt/{id}/status:
    get:
      description: Returns whether a prompt has been completed by the user. This request does not require authentication, and so can be used client-side without sharing API credentials.
      operationId: GetPromptStatus
      parameters:
      - description: The prompt identifier.
        explode: false
        in: path
        name: id
        required: true
        schema:
          type: string
        style: simple
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptStatus'
          description: OK
        400:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Invalid parameters
        404:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: A prompt with this identifier could not be found
      summary: Check prompt status
      tags:
      - approve
components:
  responses:
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Missing or invalid API key in the username basic auth field
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Invalid parameters
    PollTimeout:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Polling timed out with no user response
    PromptNotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: A prompt with this identifier could not be found
  schemas:
    Prompt:
      example:
        sent_at: 0.8008281904610115
        request:
          metadata:
            browser: browser
            operating_system: operating_system
            location: location
            time: time
            ip_address: ip_address
          long_poll: true
          reject_text: reject_text
          internal_data:
            key: internal_data
          approve_redirect_url: approve_redirect_url
          reject_redirect_url: reject_redirect_url
          idempotency_key: idempotency_key
          approve_text: approve_text
          body: body
          title: title
          user: user
          expires_in: 6.027456183070403
        metadata:
          browser: browser
          operating_system: operating_system
          location: location
          time: time
          ip_address: ip_address
        is_expired: true
        answer:
          result: true
          metadata:
            browser: browser
            operating_system: operating_system
            ip_address: ip_address
          time: 1.4658129805029452
        id: id
      properties:
        id:
          description: A unique id for this prompt.
          type: string
        sent_at:
          description: The unix timestamp when this prompt was sent.
          type: number
        is_expired:
          description: Whether the prompt can still be answered.
          type: boolean
        request:
          $ref: '#/components/schemas/CreatePromptRequest'
        answer:
          $ref: '#/components/schemas/PromptAnswer'
        metadata:
          $ref: '#/components/schemas/PromptMetadata'
      required:
      - id
      - is_expired
      - request
      - sent_at
      type: object
    CreatePromptRequest:
      example:
        metadata:
          browser: browser
          operating_system: operating_system
          location: location
          time: time
          ip_address: ip_address
        long_poll: true
        reject_text: reject_text
        internal_data:
          key: internal_data
        approve_redirect_url: approve_redirect_url
        reject_redirect_url: reject_redirect_url
        idempotency_key: idempotency_key
        approve_text: approve_text
        body: body
        title: title
        user: user
        expires_in: 6.027456183070403
      properties:
        user:
          description: The user to send the approval request to. Can be either an email address or a phone number.
          type: string
        body:
          description: The body of the approval request to show the user.
          type: string
        title:
          description: The title of an approval request. Defaults to an empty string.
          type: string
        approve_text:
          description: The approve action text. Defaults to 'Approve'.
          type: string
        approve_redirect_url:
          description: An HTTPS URL to redirect the user to if the prompt is approved. This URL is kept secret until the user is redirected to it.
          type: string
        reject_text:
          description: The reject action text. If not specified the reject button will NOT be rendered, and the user will only see an approve action button.
          type: string
        reject_redirect_url:
          description: An HTTPS URL to redirect the user to if the prompt is rejected. This URL is kept secret until the user is redirected to it.
          type: string
        long_poll:
          description: If true, the request waits (long-polls) until the user responds to the prompt or more than 10 minutes pass. Defaults to false.
          type: boolean
        expires_in:
          description: The number of seconds until this request can no longer be answered.
          type: number
        metadata:
          $ref: '#/components/schemas/PromptMetadata'
        internal_data:
          additionalProperties:
            type: string
          type: object
        idempotency_key:
          description: Allows calling `create_prompt` multiple times idempotently, such that a prompt is sent at-most once. This key should contain sufficient randomness. Idempotent requests are stored for 24 hours. After that time, the same key will create a new request.
          type: string
      required:
      - body
      - user
      type: object
    PromptMetadata:
      example:
        browser: browser
        operating_system: operating_system
        location: location
        time: time
        ip_address: ip_address
      properties:
        location:
          description: The physical location, like Oakland, CA, of the action.
          type: string
        time:
          description: The date/time of the action.
          type: string
        ip_address:
          description: The IP address of the computer initiating the action.
          type: string
        browser:
          description: The web browser initiating the action, i.e. Chrome.
          type: string
        operating_system:
          description: The operating system initiating the action, i.e. Mac OS X.
          type: string
      type: object
    PromptInternalData:
      additionalProperties:
        type: string
      type: object
    PromptAnswer:
      example:
        result: true
        metadata:
          browser: browser
          operating_system: operating_system
          ip_address: ip_address
        time: 1.4658129805029452
      properties:
        result:
          description: The user's answer to whether or not they approve this prompt.
          type: boolean
        time:
          description: The unix timestamp when the user answered the prompt.
          type: number
        metadata:
          $ref: '#/components/schemas/AnswerMetadata'
      required:
      - result
      - time
      type: object
    AnswerMetadata:
      example:
        browser: browser
        operating_system: operating_system
        ip_address: ip_address
      properties:
        ip_address:
          type: string
        browser:
          type: string
        operating_system:
          type: string
      type: object
    PromptStatus:
      example:
        is_expired: true
        is_answered: true
      properties:
        is_answered:
          description: Whether the prompt has been answered or not.
          type: boolean
        is_expired:
          description: Whether the prompt can still be answered.
          type: boolean
      required:
      - is_answered
      - is_expired
      type: object
    Error:
      properties:
        error:
          description: A human readable API error message.
          type: string
      required:
      - error
      type: object
  securitySchemes:
    apiKey:
      scheme: basic
      type: http