Back to top

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.

hierarchy

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.

Get Authentication Token
GET/api/authenticate

Example URI

GET /api/authenticate
Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Response  200
HideShow

The login request was successful, and a valid session token is returned

Headers
Content-Type: application/json
Body
{
  "token": "MjQ1ZTY3Y2UtMDZjMC00NTFlLWEwNTUtMzMwYjgxODhlMGQ5"
}
Response  401
HideShow

Invalid credentials

Response  500
HideShow

Internal System Error

API Commands

Chain Item Actions

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 Item
PUT/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

PUT /api/chains/d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e/items/1cbe149a-59f2-425f-ac02-2d0ea3e3a7fe
URI Parameters
HideShow
chainId
guid (required) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e

ID of the Chain

itemId
guid (required) Example: 1cbe149a-59f2-425f-ac02-2d0ea3e3a7fe

ID of the Item

Request
HideShow
  • 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"
  }
}
Response  202
HideShow

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"
}
Response  400
HideShow

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]"
    }
  ]
}
Response  404
HideShow

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
}
Response  409
HideShow

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
}
Response  500
HideShow

Internal System Error

[GET] Chain Item
GET/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

GET /api/chains/d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e/items/1cbe149a-59f2-425f-ac02-2d0ea3e3a7fe
URI Parameters
HideShow
chainId
guid (required) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e

ID of the Chain

itemId
guid (required) Example: 1cbe149a-59f2-425f-ac02-2d0ea3e3a7fe

ID of the Item

Request
HideShow
  • Note: Request must include a valid authentication token
Headers
Content-Type: application/json
Authorization: Bearer {token}
Response  200
HideShow

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": {
    "input-name1": "Input value",
    "input-name2": "Input value 2"
  },
  "outputs": {
    "output-name1": "Completed output value",
    "output-name2": "Another completed output value"
  },
  "completedAt": "2017-06-23T18:43:45.403Z",
  "batchId": "782d9725-03f6-0000-1817-08d4cac09398"
}
Response  404
HideShow

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
}
Response  500
HideShow

Internal System Error

[DELETE] Chain Item
DELETE/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

DELETE /api/chains/d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e/items/1cbe149a-59f2-425f-ac02-2d0ea3e3a7fe
URI Parameters
HideShow
chainId
guid (required) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e

ID of the Chain

itemId
guid (required) Example: 1cbe149a-59f2-425f-ac02-2d0ea3e3a7fe

ID of the Item

Request
HideShow
  • Note: Request must include a valid authentication token
Headers
Content-Type: application/json
Authorization: Bearer {token}
Response  202
HideShow

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": {
    "input-name1": "Input value",
    "input-name2": "Input value 2"
  },
  "batchId": "782d9725-03f6-0000-1817-08d4cac09398"
}
Response  404
HideShow

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
}
Response  405
HideShow

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
}
Response  500
HideShow

Internal System Error

Workflow Item Actions

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 Item
PUT/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

PUT /api/workflows/d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e/items/1cbe149a-59f2-425f-ac02-2d0ea3e3a7fe
URI Parameters
HideShow
workflowId
guid (required) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e

ID of the Workflow

itemId
guid (required) Example: 1cbe149a-59f2-425f-ac02-2d0ea3e3a7fe

ID of the Item

Request
HideShow
  • 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"
  }
}
Response  202
HideShow

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"
}
Response  400
HideShow

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]"
    }
  ]
}
Response  404
HideShow

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
}
Response  409
HideShow

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
}
Response  500
HideShow

Internal System Error

[GET] Workflow Item
GET/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

GET /api/workflows/d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e/items/1cbe149a-59f2-425f-ac02-2d0ea3e3a7fe
URI Parameters
HideShow
workflowId
guid (required) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e

ID of the Workflow

itemId
guid (required) Example: 1cbe149a-59f2-425f-ac02-2d0ea3e3a7fe

ID of the Item

Request
HideShow
  • Note: Request must include a valid authentication token
Headers
Content-Type: application/json
Authorization: Bearer {token}
Response  200
HideShow

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": {
    "input-name1": "Input value",
    "input-name2": "Input value 2"
  },
  "outputs": {
    "output-name1": "Completed output value",
    "output-name2": "Another completed output value"
  },
  "completedAt": "2017-06-23T18:43:45.403Z",
  "batchId": "782d9725-03f6-0000-1817-08d4cac09398"
}
Response  404
HideShow

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
}
Response  500
HideShow

Internal System Error

[DELETE] Workflow Item
DELETE/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

DELETE /api/workflows/d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e/items/1cbe149a-59f2-425f-ac02-2d0ea3e3a7fe
URI Parameters
HideShow
workflowId
guid (required) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e

ID of the Workflow

itemId
guid (required) Example: 1cbe149a-59f2-425f-ac02-2d0ea3e3a7fe

ID of the Item

Request
HideShow
  • Note: Request must include a valid authentication token
Headers
Content-Type: application/json
Authorization: Bearer {token}
Response  200
HideShow

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": {
    "input-name1": "Input value",
    "input-name2": "Input value 2"
  },
  "batchId": "782d9725-03f6-0000-1817-08d4cac09398"
}
Response  404
HideShow

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
}
Response  405
HideShow

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
}
Response  500
HideShow

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.

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 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. 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!
}

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 Response
POST/

Example URI

POST /
Request
HideShow
  • 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": {
    "input-name1": "value1",
    "input-name2": "value2"
  },
  "outputs": {
    "output-name1": "value1",
    "output-named": "value2"
  },
  "batchId": "106b4833-1d70-46c0-9dc2-75ea469c7044",
  "chainId": "1ca62230-4fb5-11e7-b76a-6d800f150a6c"
}
Response  200
HideShow

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 Response
POST/

Example URI

POST /
Request
HideShow
  • 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": {
    "input-name1": "value1",
    "input-name2": "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"
}
Response  200
HideShow

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
{}

Generated by aglio on 11 Oct 2017