OneSpace Project Center API
Note: This documention covers the Project Center Client API released in June of 2017. If you are using our legacy API for managed projects, that documentation can be found here: OneSpace Legacy API Guide
Introduction ¶
OneSpace Project Center is a platform for managing work with a team of freelancers or private contributors. This tool empowers businesses to leverage an on-demand workforce in a way that seamlessly blends with an existing enterprise data ecosystem.
The Project Center API provides a simple REST interface to integrate data flows between OneSpace and other critical business processes. This API is an asynchronous, event-driven interface for pushing items into the platform and retrieving completed results. This API has been designed to easily integrate with a variety of existing business data flow processes and tools, bridging the gap between existing enterprise tools and the OneSpace platform.
REST API
This API is a RESTful web service that handles asynchronous communication with the OneSpace platform. For additional information on REST fundamentals, please see REpresentational State Transfer
Each action against the OneSpace API is stateless, containing the full information and parameters required to take an action.
Session Management
This API utilizes token based authorization. All requests into this API require a valid session token. Applications using this API must initially make an authentication request to retrieve a session token. This request passes in credential using basic auth and returns a session token that must be included in subsequent requests.
A given session token will be active for a period of time between 12 and 24hrs before needing to be re-requested. When expired, a general API request will return a 401 “Unauthorized” response, and the client application will need to request a new token.
Item Request Tracking
The Project Center API is idempotent, meaning that each item submitted is processed only once, even if it is delivered multiple times. To facilitate this, all requests require a unique input key for every item. A common practice is to use a GUID (Globally unique identifier) for this key.
Each request into this API can be independently tracked using the supplied request key.
Terminology ¶
Projects
In Project Center, projects are the high-level containers that allow users to organize a collection of jobs for freelancers and internal contributors. Although the API does not directly reference projects, all of the workflows and chains that receive items are nested under a Project Center Project.
Workflows
Workflows in Project Center facilitate the completion of work. A workflow contains one or more Assignments that present work to contributors. Workflows that contain multiple assignments are typically used to add edit or review steps to determine whether or not the original submission should be accepted as output. Think of workflows as the “engine” by which items are completed within Project Center.
Chains
Like workflows, Chains are also “engines” that complete units of work in Project Center. Chains, however, send items through multiple workflows based on business logic. This can be thought of like an automated flowchart, automatically routing items to different workflows based on the state of each item. From an API perspective, these operate just like workflows, in that items are individually released and processed through a chain.
Items
An item represents a single unit of work that can be completed by a workflow or a workflow chain. Items contain a set of inputs (provided by the client) and outputs (created within workflows or chains). These are the lowest level unit of work moving into and out of Project Center.
Batches
Batches represent a logical grouping of items moving through a Project Center workflow or chain. When a client submits work through the user interface, each uploaded file creates a single batch. These can then be tracked, monitored, or exported as a unit. API submissions by default will reside in an automatically generated API batch.
API Authentication ¶
Authentication Tokens
This API utilizes token-based authorization, and all requests into this API require a valid session token. Applications using this API must initially make an authentication request to retrieve a session token. This request passes in credential using basic auth and returns a session token that must be included in subsequent requests.
A given session token will be active for 12hrs before needing to be requested again. When expired, a general API request will return a 401 “Unauthorized” response, and the client application will need to request a new token.
Get Authentication Token ¶
This function should be used on application startup or after session timeout to retrieve a new authentication token. The returned token must be included in the headers of all general API requests.
- The request accepts credentials via Basic Auth
Get Authentication TokenGET/api/authenticate
Example URI
Headers
Content-Type: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
200
The login request was successful, and a valid session token is returned
Headers
Content-Type: application/json
Body
{
"Token": "MjQ1ZTY3Y2UtMDZjMC00NTFlLWEwNTUtMzMwYjgxODhlMGQ5"
}
401
Invalid credentials
500
Internal System Error
Item Commands ¶
This section includes commands for interacting with individual items of work on the OneSpace platform. This includes pushing work into the system, canceling items, and retreiving the status and output of finished items.
Chain Item Commands ¶
These operations interact with single chain items. Items are published into the system using PUT supplying a unique ID. This ID can be later used to reference the item for different actions.
[PUT] Chain ItemPUT/api/chains/{chainId}/items/{itemId}
Publishes an item into the supplied Workflow Chain. Note that this request can be tracked via the given item ID, which will also be returned to the user application in the response webhook. The Chain ID is retrieved for a given chain through the Project Center application, and will not change after the chain has been created.
Example URI
- chainId
guid
(required) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315eID of the Chain
- itemId
guid
(required) Example: 1cbe149a-59f2-425f-ac02-2d0ea3e3a7feID of the Item
-
Note: Request must include a valid authentication token
-
inputs: Includes key value pairs of input values for the workflow chain item
Headers
Content-Type: application/json
Authorization: Bearer {token}
Body
{
"inputs": {
"name1": "value1",
"name2": "value2"
}
}
202
The request has been accepted and has passed initial validation. The final response will be an asynchronous response sent as a OneSpace webhook.
-
id : The ID of the item passed in
-
status : Status of the item (on success, it should be “pending”)
-
inputs : The key, value pairs of all of the input values for the item
-
batchId : The ID of the batch that contains the item
Body
{
"id": "1cbe149a-59f2-425f-ac02-2d0ea3e3a7fe",
"status": "pending",
"inputs": {
"name1": "value1",
"name2": "value2"
},
"batchId": "dfbd78ba-7d80-46a0-b01b-f14261f61b38"
}
400
Bad Request: Invalid put request - please see error message for more details
-
code : System error code
-
message : Human-readable error message
-
data : Additional data for the error message (if needed)
Body
{
"code": 400,
"message": "The request input fields did not match the chain schema.",
"data": [
{
"ValidationError": "Unknown columns: [api-input]"
}
]
}
404
Resource not found: Improper URI for this operation
-
code : System error code
-
message : Human-readable error message
-
data : Additional data for the error message (if needed)
Body
{
"code": 404,
"message": "Resource not found",
"data": null
}
409
The supplied item ID has already been requested
-
code : System error code
-
message : Human-readable error message
-
data : Additional data for the error message (if needed)
Body
{
"code": 409,
"message": "The provided item already exists",
"data": null
}
500
Internal System Error
[GET] Chain ItemGET/api/chains/{chainId}/items/{itemId}
Retrieves the state of a given chain item. This can be used to check the status of an item or to retrieve completed results.
Example URI
- chainId
guid
(required) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315eID of the Chain
- itemId
guid
(required) Example: 1cbe149a-59f2-425f-ac02-2d0ea3e3a7feID of the Item
- Note: Request must include a valid authentication token
Headers
Content-Type: application/json
Authorization: Bearer {token}
200
The request has been accepted and has passed initial validation. The final response will be an asynchronous response sent as a OneSpace webhook. Note that the outputs
and completedAt
elements are only present when item processing has been completed.
-
id : The ID of the item passed in
-
status : Status of the item (“open”, “completed”, “canceled”, etc.)
-
chainId : The ID of the chain for the item
-
batchId : The ID of the batch that contains the item
-
inputs : The key, value pairs of all of the input values for the item
-
outputs : The key, value pairs of all of the output values (generated by OneSpace) for the item (only displayed if item is complete)
-
completedAt : UTC timestamp when the item was completed (only displayed if item is complete)
Body
{
"id": "5a578946-5ea9-4691-be1f-f208d9f8dde1",
"chainId": "cabd4990-3409-11e7-94a7-27dfad15f1af",
"status": "completed",
"addedAt": "2017-06-23T18:36:56.27Z",
"inputs": {
"input1": "Input value",
"myInput": "Input value 2"
},
"outputs": {
"output1": "Completed output value",
"myOutput": "Another completed output value"
},
"completedAt": "2017-06-23T18:43:45.403Z",
"batchId": "782d9725-03f6-0000-1817-08d4cac09398"
}
404
Bad Request: Invalid put request - please see error message for more details
-
code : System error code
-
message : Human-readable error message
-
data : Additional data for the error message (if needed)
Body
{
"code": 400,
"message": "Could not find item 71bb3969-19e1-44c8-93e8-541e0e7ca752 for workflow 20a1f60d-1d70-0000-f270-08d45757cd22",
"data": null
}
500
Internal System Error
[DELETE] Chain ItemDELETE/api/chains/{chainId}/items/{itemId}
Cancels the given chain item. This will prevent the item from being served to any contributors. Note that items that are currently in progress are not canceled until after the user submits or abandons their open task.
Example URI
- chainId
guid
(required) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315eID of the Chain
- itemId
guid
(required) Example: 1cbe149a-59f2-425f-ac02-2d0ea3e3a7feID of the Item
- Note: Request must include a valid authentication token
Headers
Content-Type: application/json
Authorization: Bearer {token}
202
The given item was successfully canceled.
-
id : The ID of the item passed in
-
status : Status of the item (“canceled”)
-
chainId : The ID of the chain for the item
-
batchId : The ID of the batch that contains the item
-
inputs : The key, value pairs of all of the input values for the item
-
addedAt : UTC timestamp when the item was uploaded.
Body
{
"id": "5a578946-5ea9-4691-be1f-f208d9f8dde1",
"chainId": "cabd4990-3409-11e7-94a7-27dfad15f1af",
"status": "canceled",
"addedAt": "2017-06-23T18:36:56.27Z",
"inputs": {
"input1": "Input value",
"myInput": "Input value 2"
},
"batchId": "782d9725-03f6-0000-1817-08d4cac09398"
}
404
Bad Request: Item not found. The given item ID was not found for your user or chain
-
code : System error code
-
message : Human-readable error message
-
data : Additional data for the error message (if needed)
Body
{
"code": 400,
"message": "Could not find item 71bb3969-19e1-44c8-93e8-541e0e7ca752 for chain 20a1f60d-1d70-0000-f270-08d45757cd22",
"data": null
}
405
Bad Request: Item was not in a state that could be canceled (either “completed” or “canceled”)
-
code : System error code
-
message : Human-readable error message
-
data : Additional data for the error message (if needed)
Body
{
"code": 405,
"message": "Could not cancel item 71bb3969-19e1-44c8-93e8-541e0e7ca752 for chain 20a1f60d-1d70-0000-f270-08d45757cd22",
"data": null
}
500
Internal System Error
Workflow Item Commands ¶
These operations interact with single workflow items. Items are published into the system using PUT supplying a unique ID. This ID can be later used to reference the item for different actions.
[PUT] Workflow ItemPUT/api/workflows/{workflowId}/items/{itemId}
Publishes an item into the supplied Workflow. Note that this request can be tracked via the given item ID, which will also be returned to the user application in the response webhook. The Workflow ID is retrieved for a given workflow through the Project Center application, and will not change after the workflow has been created.
Example URI
- workflowId
guid
(required) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315eID of the Workflow
- itemId
guid
(required) Example: 1cbe149a-59f2-425f-ac02-2d0ea3e3a7feID of the Item
-
Note: Request must include a valid authentication token
-
inputs: Includes key value pairs of input values for the workflow item
Headers
Content-Type: application/json
Authorization: Bearer {token}
Body
{
"inputs": {
"name1": "value1",
"name2": "value2"
}
}
202
The request has been accepted and has passed initial validation. The final response will be an asynchronous response sent as a OneSpace webhook.
-
id : The ID of the item passed in
-
status : Status of the item (on success, it should be “pending”)
-
inputs : The key, value pairs of all of the input values for the item
-
batchId : The ID of the batch that contains the item
Body
{
"id": "1cbe149a-59f2-425f-ac02-2d0ea3e3a7fe",
"status": "pending",
"inputs": {
"name1": "value1",
"name2": "value2"
},
"batchId": "dfbd78ba-7d80-46a0-b01b-f14261f61b38"
}
400
Bad Request: Invalid put request - please see error message for more details
-
code : System error code
-
message : Human-readable error message
-
data : Additional data for the error message (if needed)
Body
{
"code": 400,
"message": "The request input fields did not match the workflow schema.",
"data": [
{
"ValidationError": "Unknown columns: [api-input]"
}
]
}
404
Resource not found: Improper URI for this operation
-
code : System error code
-
message : Human-readable error message
-
data : Additional data for the error message (if needed)
Body
{
"code": 404,
"message": "Resource not found",
"data": null
}
409
The supplied item ID has already been requested
-
code : System error code
-
message : Human-readable error message
-
data : Additional data for the error message (if needed)
Body
{
"code": 409,
"message": "The provided item already exists",
"data": null
}
500
Internal System Error
[GET] Workflow ItemGET/api/workflows/{workflowId}/items/{itemId}
Retrieves the state of a given workflow item. This can be used to check the status of an item or to retrieve completed results.
Example URI
- workflowId
guid
(required) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315eID of the Workflow
- itemId
guid
(required) Example: 1cbe149a-59f2-425f-ac02-2d0ea3e3a7feID of the Item
- Note: Request must include a valid authentication token
Headers
Content-Type: application/json
Authorization: Bearer {token}
200
The request has been accepted and has passed initial validation. The final response will be an asynchronous response sent as a OneSpace webhook. Note that the outputs
and completedAt
elements are only present when item processing has been completed.
-
id : The ID of the item passed in
-
status : Status of the item (“open”, “completed”, “canceled”, etc.)
-
workflowId : The ID of the workflow for the item
-
batchId : The ID of the batch that contains the item
-
inputs : The key, value pairs of all of the input values for the item
-
outputs : The key, value pairs of all of the output values (generated by OneSpace) for the item (only displayed if item is complete)
-
completedAt : UTC timestamp when the item was completed (only displayed if item is complete)
Body
{
"id": "5a578946-5ea9-4691-be1f-f208d9f8dde1",
"workflowId": "cabd4990-3409-11e7-94a7-27dfad15f1af",
"status": "completed",
"addedAt": "2017-06-23T18:36:56.27Z",
"inputs": {
"input1": "Input value",
"myInput": "Input value 2"
},
"outputs": {
"output1": "Completed output value",
"myOutput": "Another completed output value"
},
"completedAt": "2017-06-23T18:43:45.403Z",
"batchId": "782d9725-03f6-0000-1817-08d4cac09398"
}
404
Bad Request: Invalid put request - please see error message for more details
-
code : System error code
-
message : Human-readable error message
-
data : Additional data for the error message (if needed)
Body
{
"code": 400,
"message": "Could not find item 71bb3969-19e1-44c8-93e8-541e0e7ca752 for workflow 20a1f60d-1d70-0000-f270-08d45757cd22",
"data": null
}
500
Internal System Error
[DELETE] Workflow ItemDELETE/api/workflows/{workflowId}/items/{itemId}
Cancels the given workflow item. This will prevent the item from being served to any contributors. Note that items that are currently in progress are not canceled until after the user submits or abandons their open task.
Example URI
- workflowId
guid
(required) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315eID of the Workflow
- itemId
guid
(required) Example: 1cbe149a-59f2-425f-ac02-2d0ea3e3a7feID of the Item
- Note: Request must include a valid authentication token
Headers
Content-Type: application/json
Authorization: Bearer {token}
200
The item was successfully canceled
-
id : The ID of the item passed in
-
status : Status of the item (“canceled”)
-
workflowId : The ID of the workflow for the item
-
batchId : The ID of the batch that contains the item
-
inputs : The key, value pairs of all of the input values for the item
-
addedAt : UTC timestamp when the item was submitted.
Body
{
"id": "5a578946-5ea9-4691-be1f-f208d9f8dde1",
"workflowId": "cabd4990-3409-11e7-94a7-27dfad15f1af",
"status": "completed",
"addedAt": "2017-06-23T18:36:56.27Z",
"inputs": {
"input1": "Input value",
"myInput": "Input value 2"
},
"batchId": "782d9725-03f6-0000-1817-08d4cac09398"
}
404
Bad Request: Item not found. The given item was not found for your account or workflow
-
code : System error code
-
message : Human-readable error message
-
data : Additional data for the error message (if needed)
Body
{
"code": 400,
"message": "Could not find item 71bb3969-19e1-44c8-93e8-541e0e7ca752 for workflow 20a1f60d-1d70-0000-f270-08d45757cd22",
"data": null
}
405
Bad Request: Item was not in a state that could be canceled (either “completed” or “canceled”)
-
code : System error code
-
message : Human-readable error message
-
data : Additional data for the error message (if needed)
Body
{
"code": 405,
"message": "Could not find item 71bb3969-19e1-44c8-93e8-541e0e7ca752 for workflow 20a1f60d-1d70-0000-f270-08d45757cd22",
"data": null
}
500
Internal System Error
Webhook Callbacks ¶
When items are completed through OneSpace Project Center, our system will deliver those completed items to API clients via webhook callback events. These webhooks are REST POST events that contain JSON data for completed items. API clients will need to run a service listening on a static IP or URL to receive these events.
Webhook Configuration
Webhooks are currently configured by the OneSpace Client Solutions team as part of the API setup process. This can be any IP or URL the client desires. Note that the configuration for webhook settings can be viewed or modified through API commands. See the Admin Commands section below for details.
Webhook Destinations
OneSpace will push webhook responses to a client service at the configured URI. As Project Center items can be completed at any time, the client webhook receiver should be available at all times. If the destination is unavailable, OneSpace will perform several additional attempts over a period of time before giving up. This can tolerate outages of up to several hours but will result in dropped responses if the destination service is down for an extended period of time.
Webhook Security
OneSpace webhook responses offer two alternatives for client-side security, allowing clients to choose their preferred method of verifying these responses come from a trusted source. These options include:
-
HMAC Security - Utilizes a shared secret key along with a cryptographic header that ensures messages are only generated from a trusted source
-
oAuth Security - OneSpace utilizes a client supplied username and password to log into a client endpoint to activate a session for delivering webhooks.
HMAC
OneSpace webhook responses utilize HMAC Security to support client-side security. By utilizing a shared secret key, these signatures enable clients to verify that webhook responses are coming from a trusted, secure source. The secure signature is included in the headers of every webhook response sent by OneSpace.
HMAC can be configured from the API Administration page on the OneSpace Project Center platform by selecting HMAC on the Company Webhook Settings Section. Upon saving the HMAC setting, the shared secret key will be displayed on the page:
To validate this signature, client applications would:
-
Create an input string from the request body (as text) and the UTC timestamp included in the header (
X-OneSpace-Timestamp
) [body text + timestamp] -
Generate an HMAC-256 hash using the input string and the (base64 decoded) secret key supplied by OneSpace
-
Compare the (base64 encoded) hash with the signature supplied in the webhook header (
X-OneSpace-Signature
)
var inputValue = Encoding.UTF8.GetBytes(string.Concat( body, timeStampUtc ));
var hashEngine = new HMACSHA256( Convert.FromBase64String( secret_key );
var binaryHash = hashEngine.ComputeHash( inputValue );
var signature = Convert.ToBase64String( binaryHash );
if (signature == onespaceSignature)
{
// Valid Webhook!
}
OAuth
When utilizing oAuth security, OneSpace will utilize a login and password to collect a session token from a client-supplied endpoint. This token will be included in the headers of every webhook response, guaranteeing that those items are being delivered from a trusted source.
oAuth can be configured from the API Administration page on the OneSpace Project Center platform utilizing the following input parameters:
-
oAuth URL: The client’s hosted endpoint OneSpace will use to log into to activate a webhook session
-
Username: The username OneSpace will use when connecting to the oAuth URL
-
Password: The password OneSpace will use when connecting to the oAuth URL
-
Access Token Field: When authenticating against the oAuth URL to retrieve an authentication token, this label tells us which field of the response to use as the access token for a given session.
OneSpace will utilize the session token for all webhook callbacks, and will log in as needed to refresh the token any time sessions expire.
Webhook Callback
This callback delivers completed items for both workflows and chains to a client application. Note that although the example listed below includes both a batch and a chain ID an actual response would contain only one of these IDs, depending on the item type.
Responding to the Webhook
OneSpace will accept an HTTP response of 200 as a valid receipt of the message. Anything else will be interpreted as a failure, sending the response into the exponential back-off retry cycle.
Workflow Webhook Response ¶
This function delivers a completed worflow item to a client application, delivering all of the inputs and outputs for the given item in a workflow. Note that this will use the full URI as configured for the client.
Expand the “Request” section below for details on the webhook format
Workflow Webhook ResponsePOST/
Example URI
-
itemId - Input ID of the item as it was submitted originally - DEPRECATED (use “id”)
-
id - Input ID of the item as it was submitted originally
-
inputs - name/value pairs of all of the item inputs as specified by the user
-
outputs - name/value pairs of all of the Project Center generated values on the item
-
batchId - The ID of the batch for the given item
-
chainId - The ID of the chain for the item (if applicable)
-
workflowId - The ID of the chain for the item (if applicable)
Headers
Content-Type: application/json
Authorization: Bearer {token}
X-OneSpace-Timestamp: {Timestamp}
X-OneSpace-Signature: {hmac-signature}
Body
{
"id": "83d3e829-6c90-4af9-9b01-507a56f3eb2a",
"inputs": {
"input1": "value1",
"myInput": "value2"
},
"outputs": {
"output1": "value1",
"myOutput": "value2"
},
"batchId": "106b4833-1d70-46c0-9dc2-75ea469c7044",
"chainId": "1ca62230-4fb5-11e7-b76a-6d800f150a6c"
}
200
Successful Response
Note that this is the expected response to a webhook callback. OneSpace will assume any other response code is an error that must be retried.
Body
{}
Chaining Webhook Response ¶
This function delivers a completed chain item to a client application, delivering all of the inputs and outputs for the given item. Note that this will use the full URI as configured for the client.
Chaining Webhook Responses will always include all outputs from each workflow that an item has completed on its path through a chain. This could result in a dynamic number of outputs for items taking different paths through a chain.
Expand the “Request” section below for details on the webhook format
Chaining Webhook ResponsePOST/
Example URI
-
itemId - Input ID of the item as it was submitted originally - DEPRECATED (use “id”)
-
id - Input ID of the item as it was submitted originally
-
inputs - name/value pairs of all of the item inputs as specified by the user
-
outputs - name/value pairs of all of the Project Center generated values on the item, prepended with the GUID of the workflow it was output from
-
batchId - The ID of the batch for the given item
-
chainId - The ID of the chain for the item (if applicable)
-
workflowId - The ID of the chain for the item (if applicable)
Headers
Content-Type: application/json
Authorization: Bearer {token}
X-OneSpace-Timestamp: {Timestamp}
X-OneSpace-Signature: {hmac-signature}
Body
{
"id": "83d3e829-6c90-4af9-9b01-507a56f3eb2a",
"inputs": {
"input1": "value1",
"myInput": "value2"
},
"outputs": {
"987b4833-1d70-46c0-9dc2-75ea469c7044/output-name1": "value1",
"987b4833-1d70-46c0-9dc2-75ea469c7044/output-name2": "value2",
"123b4833-4fb5-11e7-b76a-6d800f150a6c/output-name1": "value3",
"123b4833-4fb5-11e7-b76a-6d800f150a6c/output-named": "value4"
},
"batchId": "106b4833-1d70-46c0-9dc2-75ea469c7044",
"chainId": "1ca62230-4fb5-11e7-b76a-6d800f150a6c"
}
200
Successful Response
Note that this is the expected response to a webhook callback. OneSpace will assume any other response code is an error that must be retried.
Body
{}
Webhook Commands ¶
These operations enable reading or setting the webhook configuraitons for your applications. These can be set at a company default level (which becomes the target for any workflows or chains that have not explicitly set a webhook URI.
[GET] All WebhooksGET/api/webhooks/
Retrieves a catalog listign of all company webhook URI destinations, including the company default as well as any explicit values that were set for a workflow or workflow chain.
Example URI
- Note: Request must include a valid authentication token
Headers
Content-Type: application/json
Authorization: Bearer {token}
200
The request has been accepted and the result is your default webhook for your account.
-
defaulUrl : The default webhook on your account
-
workflows : An array of any workflows that have had a webhook destination set, by ID and target URL
-
chains : An array of any chains that have had a webhook destination set, by ID and target URL
Body
{
"defaultUrl": "https://www.yourwebhook.com/webhook/uri",
"workflows": [
{
"workflowId": "cabd4990-3409-11e7-94a7-27dfad15f1af",
"webhookUrl": "https://www.yourwebhook.com/webhook/uri"
}
],
"chains": [
{
"chainId": "cabd4990-3409-11e7-94a7-27dfad15f1af",
"webhookUrl": "https://www.yourwebhook.com/webhook/uri"
}
]
}
500
Internal System Error
[GET] Default WebhookGET/api/webhooks/default
Retreives the current company default webhook URI.
Example URI
- Note: Request must include a valid authentication token
Headers
Content-Type: application/json
Authorization: Bearer {token}
200
The request has been accepted and the result is your default webhook for your account.
- defaulUrl : The default webhook on your account
Body
{
"defaultUrl": "https://www.yourwebhook.com/webhook/uri",
}
500
Internal System Error
[POST] Webhook DefaultPOST/api/webhooks/default
Sets the company default webhook URL to an explicit value, overwriting any previously set value. Note that this is the webhook destination used by default unless specified at the chain or workflow level.
Example URI
-
Note: Request must include a valid authentication token
-
defaultUrl: A string representation of the new desired default webhook URL
Headers
Content-Type: application/json
Authorization: Bearer {token}
Body
{
"defaultUrl": "https://www.yourwebhook.com/webhook/uri"
}
200
The request has been accepted and your webhook has been updated to the newly defined webhook.
- defaultUrl : The webhook URL value that was passed in to the POST
Body
{
"defaultUrl": "https://www.yourwebhook.com/webhook/uri"
}
400
Bad Request: Invalid request - please see error message for more details
-
code : System error code
-
message : Human-readable error message
-
data : Additional data for the error message (if needed)
Body
{
"code": 400,
"message": "The request body was not properly formatted",
"data": [
{
"ValidationError": "Invalid request body"
}
]
}
500
Internal System Error
Chain Webhook Commands ¶
These operations allow API users to access or change details about the webhook callbacks delivered for a specific chain. Note that when set at the chain level, a webhook URL will take precendence over the company default webhook destination. These can be explicitly set via POST, viewed via GET, or cleared via DELETE (which reverts the behavior back to use the company default webhook URL)
[POST] Chain WebhookPOST/api/chains/{chainId}/webhooks
Publishes a new webhook URL desination for the given chain.
Example URI
- chainId
guid
(required) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315eID of the Chain
-
Note: Request must include a valid authentication token
-
url: Includes a url that will be set as the webhook for the chain
Headers
Content-Type: application/json
Authorization: Bearer {token}
Body
{
"url": "https://www.yourwebhook.com/webhook/uri"
}
200
- url : Returns an object with the chainId and webhook that was sent.
Body
{
"webhookUrl": "https://www.yourwebhook.com/webhook/uri",
"chainId": "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e"
}
404
Resource not found: Improper URI for this operation
-
code : System error code
-
message : Human-readable error message
-
data : Additional data for the error message (if needed)
Body
{
"code": 404,
"message": "Resource not found",
"data": null
}
500
Internal System Error
[GET] Chain WebhookGET/api/chains/{chainId}/webhooks
Retrieves the current webhook destination set the given chain (if one has been specified)
Example URI
- chainId
guid
(required) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315eID of the Chain
- Note: Request must include a valid authentication token
Headers
Content-Type: application/json
Authorization: Bearer {token}
200
-
webhookUrl : Returns the webhook value that was sent in.
-
chainId : The ID of the chain that was passed into the request
Body
{
"webhookUrl": "https://www.yourwebhook.com/webhook/uri",
"chainId": "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e"
}
404
Bad Request: Chain not found or webhook not set.
-
code : System error code
-
message : Human-readable error message
-
data : Additional data for the error message (if needed)
Body
{
"code": 404,
"message": "There is no custom webhook for this workflow. It will use the company default which can be found by performing a GET on /api/webhooks/default",
"data": null
}
500
Internal System Error
[DELETE] Chain WebhookDELETE/api/chains/{chainId}/webhooks
Clears the currrent chain’s custom webhook. All future completed items on this chain will be sent to the default company webhook.
Example URI
- chainId
guid
(required) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315eID of the Chain
- Note: Request must include a valid authentication token
Headers
Content-Type: application/json
Authorization: Bearer {token}
204
The given item was successfully canceled.
500
Internal System Error
Workflow Webhook Commands ¶
These operations allow API users to access or change details about the webhook callbacks delivered for a specific workflow. Note that when set at the workflow level, a webhook URL will take precendence over the company default webhook destination. These can be explicitly set via POST, viewed via GET, or cleared via DELETE (which reverts the behavior back to use the company default webhook URL)
[POST] Workflow WebhookPOST/api/workflows/{workflowId}/webhooks
Publishes a new webhook for the given workflow.
Example URI
- workflowId
guid
(required) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315eID of the Workflow
-
Note: Request must include a valid authentication token
-
url: Includes a url that will be set as the webhook for the workflow
Headers
Content-Type: application/json
Authorization: Bearer {token}
Body
{
"url": "https://www.yourwebhook.com/webhook/uri"
}
200
-
webhookUrl : The webhook URL that was specified in the request
-
workflowId : The ID of the workflow that was updated
Body
{
"webhookUrl": "https://www.yourwebhook.com/webhook/uri",
"workflowId": "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e"
}
404
Resource not found: Improper URI for this operation
-
code : System error code
-
message : Human-readable error message
-
data : Additional data for the error message (if needed)
Body
{
"code": 404,
"message": "Resource not found",
"data": null
}
500
Internal System Error
[GET] Workflow WebhookGET/api/workflows/{workflowId}/webhooks
Retrieves the current webhook destination set the given workflow (if one has been specified)
Example URI
- workflowId
guid
(required) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315eID of the Workflow
- Note: Request must include a valid authentication token
Headers
Content-Type: application/json
Authorization: Bearer {token}
200
-
webhookUrl : Returns the webhook value that was sent in.
-
workflowId : The ID of the workflow that was passed into the request.
Body
{
"webhookUrl": "https://www.yourwebhook.com/webhook/uri",
"workflowId": "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e"
}
404
Bad Request: Workflow not found or schema not set.
-
code : System error code
-
message : Human-readable error message
-
data : Additional data for the error message (if needed)
Body
{
"code": 404,
"message": "There is no custom webhook for this workflow. It will use the default, which can be found by performing a GET on /api/webhooks/default",
"data": null
}
500
Internal System Error
[DELETE] Workflow WebhookDELETE/api/workflows/{workflowId}/webhooks
Clears the current workflow’s custom webhook. All future completed items on this workflow will be delivered to teh default company webhook.
Example URI
- workflowId
guid
(required) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315eID of the Workflow
- Note: Request must include a valid authentication token
Headers
Content-Type: application/json
Authorization: Bearer {token}
204
The given item was successfully canceled.
500
Internal System Error
Admin Commands ¶
These commands facilitate interacting with settings for your chains or workflows. These operations are helpful in initial application setup, but are not typically used during normal operations.
Chain Commands ¶
These operations allow users to interact with the settings for a workflow chain.
[GET] Chains (by ID)GET/api/chains/{chainId}
Retrieves detailed information about the given chain, including a listing of all valid inputs and outputs.
Example URI
- chainId
guid
(optional) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315eID of the Chain
- Note: Request must include a valid authentication token
Headers
Content-Type: application/json
Authorization: Bearer {token}
200
The response will include the complete schema for the given chain (or for all chains if no chain id parameter has been supplied.
-
id : The ID of the chain
-
name : The name of the Chain
-
inputs : An aray of inputs that can be passed into the chain
-
outputs : An array of the outputs that could potentially be exported on a chain
-
workflows : An array of the workflows that are hooked up to the chain
Body
{
"id": "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e",
"name": "OneSpace API Chain",
"inputs": [
{
"name": "Chain_Input_1"
"required": "true"
}
],
"outputs": [
{
"workflowId": "f8d2aef0-e690-0000-e3a9-08d50c299145",
"name": "Output_1"
}
],
"workflows": [
{
"id": "f8d2aef0-e690-0000-e3a9-08d50c299145",
"name": "Workflow_Name"
}
]
}
500
Internal System Error
Chain Batch Commands ¶
These operations allow users to retrieve detailed information about the batches on a chain.
[GET] All Chain BatchesGET/api/chains/{chainId}/batches?apiDefault={apiDefault}
Retrieves an array of all batches for the given chain (when no batch ID is specified). Setting the apiDefault parameter to true will return only the default batch that new items will be uploaded to.
Example URI
- chainId
guid
(required) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315eID of the Chain
- apiDefault
bool
(optional) Example: truetrue or false
- Note: Request must include a valid authentication token
Headers
Content-Type: application/json
Authorization: Bearer {token}
200
The response will include an array of batches that belong to the provided chain (or a single batch if apiDefault is set to true).
- batches : An array of batches on the chain
Body
{
"batches": [
{
"batchId": "f77e57f5-8dcd-4afc-b62a-9a2bd5c6315t",
"chainId": "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e",
"fileName": "input_file.csv",
"state": "open"
},
{
"batchId": "85b734c4-4bb0-4090-9254-a283aad85030",
"chainId": "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e",
"fileName": "another_input_file.csv",
"state": "open"
}
]
}
500
Internal System Error
[POST] Chain Batch DefaultPOST/api/chains/{chainId}/batches
This will create a new default batch that the API will use to put new items into.
Example URI
- chainId
guid
(required) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315eID of the Chain
- Note: Request must include a valid authentication token
Headers
Content-Type: application/json
Authorization: Bearer {token}
Body
{
"batchName": "MyBatchName"
}
200
The response will include the batch information for the newly created default batch.
-
batchId : The batchId that was supplied
-
chainId : The chainId that was supplied
-
fileName : The filename of the batch
-
state : The current state of the batch
Body
{
"batchId": "f77e57f5-8dcd-4afc-b62a-9a2bd5c6315t",
"chainId": "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e",
"fileName": "MyBatchName",
"state": "open"
}
500
Internal System Error
[GET] Chain BatchesGET/api/chains/{chainId}/batches/{batchId}
Retrieves the details on a speicific batch (by batch ID) on the chain.
Example URI
- chainId
guid
(required) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315eID of the Chain
- batchId
guid
(optional) Example: f77e57f5-8dcd-4afc-b62a-9a2bd5c6315tID of the Batch
- Note: Request must include a valid authentication token
Headers
Content-Type: application/json
Authorization: Bearer {token}
200
The response will include the complete schema for the given chain (or for all chains if no chain id parameter has been supplied.
-
batchId : The batchId that was supplied
-
chainId : The chainId that was supplied
-
fileName : The filename of the batch
-
state : The current state of the batch
Body
{
"batchId": "f77e57f5-8dcd-4afc-b62a-9a2bd5c6315t",
"chainId": "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e",
"fileName": "API_Batch.csv",
"state": "open"
}
500
Internal System Error
Chain Schema Commands ¶
These operations interact with the custom API Schema on a chain. When set, a custom schema defines the output format of webhooks and chain item GET responses. This schema must include a single array of values labeled “customSchema”, which explicitly define the output format of webhooks and GET functions. Responses will include only outputs that directly match elements in the custom schema, discarding outputs that are not part of that schema and inserting null values for fields not present in the item.
The POST command sets the custom schema, GET retrieves the current custom schema, and DELETE removes the custom schema, reverting to the default behavior of including all outputs
[POST] Chain SchemaPOST/api/chains/{chainId}/schema
Publishes a new custom schema for the chain.
Example URI
- chainId
guid
(required) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315eID of the Chain
-
Note: Request must include a valid authentication token
-
customSchema: Includes an array of strings with the workflowId and output name. Valid WorkflowId and output names can be discovered through a GET on the chain
Headers
Content-Type: application/json
Authorization: Bearer {token}
Body
{
"customSchema": [
"WorkflowId/OutputName",
"WorkflowId/OutputName2"
]
}
201
- customSchema : An array of string in the form of “WorkflowId/Output” used to format responses for GET and webhook requests.
Body
{
"customSchema": [
"WorkflowId/OutputName",
"WorkflowId/OutputName2"
]
}
404
Resource not found: Improper URI for this operation
-
code : System error code
-
message : Human-readable error message
-
data : Additional data for the error message (if needed)
Body
{
"code": 404,
"message": "Resource not found",
"data": null
}
500
Internal System Error
[GET] Chain SchemaGET/api/chains/{chainId}/schema
Retrieves the current custom schema (if one has been set)
Example URI
- chainId
guid
(required) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315eID of the Chain
- Note: Request must include a valid authentication token
Headers
Content-Type: application/json
Authorization: Bearer {token}
200
- customSchema : An array of string in the form of “WorkflowId/Output” used to format responses for GET and webhook requests.
Body
{
"customSchema": [
"WorkflowId/OutputName",
"WorkflowId/OutputName2"
]
}
404
Bad Request: Chain not found or schema not set.
-
code : System error code
-
message : Human-readable error message
-
data : Additional data for the error message (if needed)
Body
{
"code": 404,
"message": "No custom schema has been set. Use a POST to specify an output schema. By default, the API will include all output data.",
"data": null
}
500
Internal System Error
[DELETE] Chain SchemaDELETE/api/chains/{chainId}/schema
Removes the currrent chain output schema. GET and webhook responses will revert to the default behavior of including all output data in each response.
Example URI
- chainId
guid
(required) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315eID of the Chain
- Note: Request must include a valid authentication token
Headers
Content-Type: application/json
Authorization: Bearer {token}
200
The given item was successfully canceled.
Body
{}
404
Bad Request: Item not found. The given item ID was not found for your user or chain
-
code : System error code
-
message : Human-readable error message
-
data : Additional data for the error message (if needed)
Body
{
"code": 404,
"message": "No custom schema set",
"data": null
}
500
Internal System Error
Workflow Commands ¶
These operations interact with settings for a workflow on your account.
[GET] Workflows (all)GET/api/workflows/
Retrieves an array of detailed information for all workflows for the company.
Example URI
- Note: Request must include a valid authentication token
Headers
Content-Type: application/json
Authorization: Bearer {token}
200
The response will include the complete schema for the given workflow (or for all workflows if no workflowId parameter has been supplied.
-
id : The ID of the workflow
-
name : The name of the workflow
-
inputs : An aray of inputs that can be passed into the workflow, including which are required
-
outputs : An array of the outputs that could potentially be exported on a workflow
Body
{
"workflows" : [{
"id" : "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e",
"name" : "OneSpace API Workflow",
"inputs" : [{
"name" : "Worklfow_Input_1"
"required" : "true"
}
],
"outputs" : [{
"name" : "Output_1"
}
]
}, {
"id" : "43d8c933-a2c5-4fa5-9d8b-9a34127e2b0f",
"name" : "Another API Workflow",
"inputs" : [{
"name" : "Worklfow_Input_1"
"required" : "true"
}
],
"outputs" : [{
"name" : "Output_1"
}
]
}
]
}
500
Internal System Error
[GET] Workflows (by ID)GET/api/workflows/{workflowId}
Retrieves detailed information about the given workflow, including a listing of all valid inputs and outputs. Note that if no workflowId is supplied the GET will return an array of all workflows for the company.
Example URI
- workflowId
guid
(optional) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315eID of the Workflow
- Note: Request must include a valid authentication token
Headers
Content-Type: application/json
Authorization: Bearer {token}
200
The response will include the complete schema for the given workflow (or for all workflows if no workflowId parameter has been supplied.
-
id : The ID of the workflow
-
name : The name of the workflow
-
inputs : An aray of inputs that can be passed into the workflow, including which are required
-
outputs : An array of the outputs that could potentially be exported on a workflow
Body
{
"id": "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e",
"name": "OneSpace API Workflow",
"inputs": [
{
"name": "Worklfow_Input_1"
"required": "true"
}
],
"outputs": [
{
"name": "Output_1"
}
]
}
500
Internal System Error
Workflow Batch Commands ¶
These operations allow users to retrieve a listing of the batches for a given workflow along with the status of each.
[GET] Workflow Batches (all)GET/api/workflows/{workflowId}/batches?apiDefault={apiDefault}
Retrieves an array of batches created for this workflow. Note that this will include all batches created from the time the workflow was created. Setting the apiDefault parameter to true will return only the default batch that new items will be uploaded to.
Example URI
- workflowId
guid
(required) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315eID of the Workflow
- apiDefault
bool
(optional) Example: truetrue or false
- Note: Request must include a valid authentication token
Headers
Content-Type: application/json
Authorization: Bearer {token}
200
The response will include the complete schema for the given workflow (or for all workflows if no workflow id parameter has been supplied.
- batches : An array of batches that belong to the workflow
Body
{
"batches": [
{
"batchId": "f77e57f5-8dcd-4afc-b62a-9a2bd5c6315t",
"workflowId": "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e",
"fileName": "upload_file.csv",
"state": "complete"
},
{
"batchId": "c476e78d-f8ea-43ee-9000-80bb805a55dd",
"workflowId": "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e",
"fileName": "another_upload_file.csv",
"state": "open"
}
]
}
500
Internal System Error
[POST] Workflow Batch DefaultPOST/api/workflows/{workflowId}/batches
This will create a new default batch that the API will use to put new items into.
Example URI
- workflowId
guid
(required) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315eID of the Workflow
- Note: Request must include a valid authentication token
Headers
Content-Type: application/json
Authorization: Bearer {token}
Body
{
"batchName": "MyBatchName"
}
200
The response will include the batch information for the newly created workflow batch
-
batchId : The batchId that was supplied
-
chainId : The chainId that was supplied
-
fileName : The filename of the batch
-
state : The current state of the batch
Body
{
"batchId": "f77e57f5-8dcd-4afc-b62a-9a2bd5c6315t",
"workflowId": "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e",
"fileName": "MyBatchName",
"state": "open"
}
500
Internal System Error
[GET] Workflow BatchesGET/api/workflows/{workflowId}/batches/{batchId}
Retrieves an array of batches that belong to the workflow.
Example URI
- workflowId
guid
(required) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315eID of the Workflow
- batchId
guid
(optional) Example: f77e57f5-8dcd-4afc-b62a-9a2bd5c6315tID of the Batch
- Note: Request must include a valid authentication token
Headers
Content-Type: application/json
Authorization: Bearer {token}
200
The response will include the complete schema for the given workflow (or for all workflows if no workflow id parameter has been supplied.
-
batchId : The batchId that was supplied
-
workflowId : The workflowId that was supplied
-
fileName : The filename of the batch
-
state : The current state of the batch
Body
{
"batchId": "f77e57f5-8dcd-4afc-b62a-9a2bd5c6315t",
"workflowId": "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e",
"fileName": "API_Batch.csv",
"state": "open"
}
500
Internal System Error