Productive API

API Endpoint

This API is implemented according to JSON API spec.


API Endpoint

The latest API endpoint is https://api.productive.io/api/v2


API Changelog

Changelog is located at https://developer.productive.io/CHANGELOG.md


API change announcements via email

You will be added to the email list for API change announcements. You can later unsubscribe from this email list. We will occasionally send emails related to changes in our APIs to subscribers. If you use API integrations, it is recommended to subscribe and stay on track with updates.


Content Negotiation

Content-Type header must be set to application/vnd.api+json.

While sending bulk requests, make sure to set Content-Type to application/vnd.api+json; ext=bulk.

When Content-Type is not set as described, API will return 415 response status error.


Authorization

Most resources have authorization on them. If successfully authorized, you will get a response containing the resource; however, if you aren’t authorized then you will be given HTTP status of 401, and an error message.


Authentication

To authenticate yourself, add your API token to the X-Auth-Token header for every request.

To access your organization data, add your organzation ID to the X-Organization-Id header for every request.


API token

API token can be generated using Productive application, navigating to Settings -> API integrations -> Generate new token


Pagination

Pagination has to be set in the following style:

?page[number]=2&page[size]=20

Where page[number]= is the page you want to view, and page[size]= is the number of resources you want to return.

To check pagination settings or how many resources there are in total, check the meta section in the response of your request.

There you can see the following:
current_page - 1 by default or the value you put in page[number]
total_pages - total_count/page_size rounded up
total_count - total number of resources you have
page_size - 30 by default or the value you put in page[size]
max_page_size - 200

An example of how to use pagination:
Sending page[number]=2 and page[size]=15 will result in seeing resources from 16 to 30 on page 2, and the total_pages number will be total_count/15 rounded up.


Filtering

If you would like to add filtration to your query, you can do that by setting the supported filter parameters in the following way: ?filter[person_id]=24. In case you set filter parameter that is not supported for the query, you will get 400 status error:

{
    "errors": [
        {
            "status": 400,
            "title": "Unsupported Filter",
            "detail": "Filter 'undefined' is not supported on this endpoint"
        }
    ]
}

Filter Operations

There is also support for different filter operations. Allowed operations are:

  • eq

  • not_eq

  • contains

  • not_contain

  • gt

  • gt_eq

  • lt

  • lt_eq

To use operations for filtering, define it after the param name: ?filter[person_id][not_eq]=24.

NOTE: Not all endpoints support filter operations. If an endpoint supports filter operations, it will be listed in the documentation for that endpoint.


Sorting

To sort query results, you can use sort parameter, passing available sort params for the resource: ?sort=name. All available sort params are defined separately for each resource. You can provide desired sort order using - sign (?sort=-name), where no - defines ascending and - defines descending order by the given sort parameter. If a given parameter is not supported, Unsupported Sort error (with status 400) will be raised:

{
    "errors": [
        {
            "status": 400,
            "title": "Unsupported Sort",
            "detail": "Sort by 'unsupported' is not supported on this endpoint"
        }
    ]
}

To include related resources in the response, you must pass an include query parameter which contains a comma separated list of the wanted related resources: ?include=person,project To include nested resources use a dot (.) sparated list of related resources: ?include=person.company,parent_task.project If requested resources does not exist, Unsupported Include error (with status 400) will be raised:

{
    "errors": [
        {
            "status": 400,
            "title": "Unsupported Include",
            "detail": "Include 'userz' is not supported on this endpoint"
        }
    ]
}

After 01.08.2024. if the request does not contain the include query parameter the response wont include any related resources (as it does now)


Sparse fields

To return a subset of fiedls of a resource in the response, you must pass an fields query parameter which contains an hash of resource types with a comma separated list of wanted fields: ?fields[person]=name,last,company. The wanted fields can be any attribute or relationship of a resource. Fields can also be attributes of a relationship resource, not just the main resource. If requested field does not exist, backend will ignore that nonexisting fields, but will work with others exisitng fields.

# http://api.productive.io/api/v2/services?fields[services]=name,deal&fields[deals]=name,date&include=[deal]
{
  "data": [
    {
      "id": "1",
      "type": "services",
      "attributes": {
        "name": "Acquiring new clients"
      },
      "relationships": {
        "deal": {
          "data": {
            "type": "deals",
            "id": "9"
          }
        }
      }
    }
  ],
 "included": [
    {
      "id": "9",
      "type": "deals",
      "attributes": {
        "name": "Administration",
        "date": "2023-09-17"
      }
    }
  ],
}

Rate Limits

The API utilizes rate limiting to control the number of requests that can be made within a specified time period. This ensures fair usage of resources and prevents abuse or overloading of the server.

The rate limits are structured around a 100 requests per 10 seconds, allowing for occasional bursts of higher request rates in short intervals. If the rate limit is exceeded, the server will respond with an appropriate HTTP status code (e.g., 429 Too Many Requests), indicating that the client should slow down and comply with the rate limits.

Special consideration is given to the reports endpoint due to its resource-intensive nature. To manage its usage effectively, additional throttling measures are implemented, allowing a maximum of 10 requests within a 30-second timeframe.


Errors

400
Used when a given query param is not supported. Possible title values: Unsupported Filter, Unsupported Filter Value, Unsupported Sort, Unsupported Group

{
    "errors": [
        {
            "status": 400,
            "title": "*one of listed values*",
            "detail": "*...* is not supported on this endpoint"
        }
    ]
}

401

{
    "errors": [
        {
            "status": 401,
            "title": "Unauthenticated",
            "detail": "You are not authenticated"
        }
    ]
}

403

{
    "errors": [
        {
            "status": 403,
            "title": "Access Denied",
            "detail": "You are not authorized to access this resource"
        }
    ]
}

404

{
    "errors": [
        {
            "status": 404,
            "title": "Record Not Found",
            "detail": "The requested record was not found"
        }
    ]
}

406

{
    "errors": [
        {
            "status": 406,
            "title": "Not Acceptable",
            "detail": "The request was not accepted"
        }
    ]
}

415

{
    "errors": [
        {
            "status": 415,
            "title": "Unsupported Media Type",
            "detail": "Unsupported content type"
        }
    ]
}

422

{
    "errors": [
        {
            "status": 422,
            "title": "Invalid Attribute",
            "detail": "Unsupported content type"
        }
    ]
}

500

{
    "errors": [
        {
            "status": 500,
            "title": "Server Error",
            "detail": "An error occured on the server"
        }
    ]
}


Generated by aglio on 28 Mar 2024