Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
256 lines (255 sloc) 7.7 KB
openapi: 3.0.0
info:
description: The simple API to request a user's approval on anything via email + sms.
version: 1.0.1
title: ApproveAPISwagger
contact:
email: dev@approveapi.com
paths:
/prompt:
post:
summary: Sending a prompt
description: Creates a prompt and pushes it to the user (sends via email, sms, or
other supported protocols).
operationId: CreatePrompt
tags:
- approve
security:
- apiKey: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreatePromptRequest"
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/Prompt"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"504":
$ref: "#/components/responses/PollTimeout"
"/prompt/{id}":
get:
summary: Retrieve a prompt
description: Retrieve the prompt object with the given ID.
operationId: GetPrompt
tags:
- approve
security:
- apiKey:
[]
parameters:
- name: id
description: The identifier for a pending or completed prompt. This is returned
when you create a prompt.
in: path
required: true
schema:
type: string
- name: 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.
in: query
required: false
schema:
type: boolean
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/Prompt"
"400":
$ref: "#/components/responses/BadRequest"
"404":
$ref: "#/components/responses/PromptNotFound"
"/prompt/{id}/status":
get:
summary: Check prompt status
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
tags:
- approve
parameters:
- name: id
description: The prompt identifier.
in: path
required: true
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/PromptStatus"
"400":
$ref: "#/components/responses/BadRequest"
"404":
$ref: "#/components/responses/PromptNotFound"
servers:
- url: https://approve.sh
components:
securitySchemes:
apiKey:
type: http
scheme: basic
responses:
Unauthorized:
description: Missing or invalid API key in the username basic auth field
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
BadRequest:
description: Invalid parameters
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
PollTimeout:
description: Polling timed out with no user response
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
PromptNotFound:
description: A prompt with this identifier could not be found
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
schemas:
Prompt:
type: object
required:
- id
- sent_at
- is_expired
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
answer:
$ref: "#/components/schemas/PromptAnswer"
metadata:
$ref: "#/components/schemas/PromptMetadata"
CreatePromptRequest:
type: object
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"
required:
- user
- body
PromptMetadata:
type: object
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
PromptAnswer:
type: object
required:
- result
- time
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:
description: Metadata about the device the user answered the prompt on
$ref: "#/components/schemas/AnswerMetadata"
AnswerMetadata:
type: object
properties:
ip_address:
type: string
browser:
type: string
operating_system:
type: string
PromptStatus:
type: object
required:
- is_answered
- is_expired
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
Error:
type: object
required:
- error
properties:
error:
description: A human readable API error message.
type: string
You can’t perform that action at this time.