Productive API
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"
}
]
}
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 18 Mar 2024