API Reference
Introduction
The SimWorkflow API is closely follows REST semantics and relies on standard HTTP codes to signal operation outcomes.
JSON will be returned in all responses from the API, including errors.
API endpoint base URL
https://api.simworkflow.com/
Authentication
You authenticate to the SimWorkflow API by providing one of your personal access tokens in the request. You can manage your personal access tokens from your account. Your personal access tokens carry many privileges, so be sure to keep them secret!
Do not share your personal access tokens in publicly accessible areas such GitHub, client-side code, and so forth.
Authentication to the API occurs via HTTP authorization bearer token header.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.
Example request
curl \
--request "GET" \
--header "Authorization: Bearer ${PERSONAL_ACCESS_TOKEN}" \
--url "https://api.simworkflow.com/workflow-definitions"
Errors
SimWorkflow uses conventional HTTP response codes to indicate success or failure of an API request.
In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information, and codes in the 5xx range indicate an error with SimWorkflow's servers.
Example error response body
{
"status": 401,
"error": "Unauthorized",
"message": "Missing authentication token"
}
Error response body fields
|
Field |
Description |
|---|---|
|
|
|
|
|
A short string describing the error that occurred. |
|
|
A human-readable message giving more details about the error. |
Rate limits
In general we allow applications that integrate with SimWorkflow to make no more than one request per second per user. We do this to help the performance of the service, and to ensure fair usage for all SimWorkflow users. Rate limiting ensures that calls to the SimWorkflow API do not exceed the maximum allowed API request limits.
If you exceed an API rate limit, you get a HTTP 429 Too Many Requests error.
The following table shows the rate limits.
|
Free |
Team |
|---|---|
|
1 request per user / second |
5 requests per user / second |
|
100 requests per organization / 60 seconds |
1,000 requests per organization / 60 seconds |
API specification
Workflow definition
- Workflow definition object
- Create a workflow definition
- Get a workflow definition
- Update a workflow definition
- Disable a workflow definition
- Enable a workflow definition
- List workflow definitions
- Get workflow definition variables
- Get a workflow definition variable value
- Add or update a workflow definition variable value
- Delete a workflow definition variable