---
agentTools:
  projectIndex: https://developers.9spokes.io/llms.txt
---

# API Structure

[block:api-header]
{
  "title": "Requests"
}
[/block]

The 9Spokes API organizes data in a RESTful manner. This means data resources are organized hierarchically, with the `company` object being the topmost resource in most cases.

[block:api-header]
{
  "title": "Responses"
}
[/block]

All API responses adhere to a strict JSON data format making it easy for app developers to parse success & error responses. The `content-type` is always `application/json` and the response body is always an object containing, at the very least, a `status` key. The value of `status` is either `ok` for successes or `err` for errors.

HTTP status codes are used to further categorize the response. The table below denotes all the supported HTTP response codes.

[block:parameters]
{
  "data": {
    "0-0": "**HTTP Code**",
    "0-1": "**Meaning**",
    "0-2": "**Corrective Action**",
    "1-0": "**200** ",
    "1-1": "*OK*",
    "1-2": "The request was processed successfully.",
    "2-1": "*Bad Request*",
    "2-2": "The request is invalid. Check the format of your request and try again.",
    "2-0": "**400**",
    "3-0": "**401**",
    "3-1": "*Unauthorized*",
    "3-2": "The API key is not accepted.",
    "4-1": "*Forbidden*",
    "4-0": "**403**",
    "4-2": "The request is denied, however the API key may be valid.",
    "5-0": "**404**",
    "5-1": "*Not Found*",
    "5-2": "The specified resource does not exist.",
    "6-0": "**405**",
    "6-1": "*Method Not Allowed*",
    "6-2": "Only the documented HTTP verbs are supported.",
    "7-0": "**429**",
    "7-1": "*Too Many Requests*",
    "8-1": "*Internal Server Error*",
    "7-2": "You have hit a rate limit. Reduce your request rate.",
    "8-0": "**500**",
    "8-2": "An internal error has occurred processing your request.",
    "9-0": "**503**",
    "9-1": "*Service Unavailable*",
    "9-2": "The API is temporarily unavailable."
  },
  "cols": 3,
  "rows": 10
}
[/block]

[block:api-header]
{
  "title": "Success Response"
}
[/block]

Successful responses yield a HTTP status code of `200` and a JSON body similar to the structure below:

The `status` key is set to `ok` and the `details` key is present.

[block:callout]
{
  "type": "info",
  "body": "Depending on the context of the request, the value of `details` could either be an object or an array."
}
[/block]

[block:api-header]
{
  "title": "Error Response"
}
[/block]

API requests that could not be processed will carry a HTTP code that is greater than `399` and a body similar to the structure shown here.

[block:api-header]
{
  "title": "Correlation ID"
}
[/block]

A `correlationId` is included in both successful and error response. Please provide this ID if you are contacting 9Spokes support regarding an issue.

[block:api-header]
{
  "title": ""
}
[/block]