The Forecast API is a complete programmable interface to all Forecast functionality.
This is a REST-style API that uses JSON for serialization and HTTP.
Fair use policy : https://www.forecast.app/fair-use-policy
A ton of stuff! We've exposed all the needed services for you to use in your applications.
You'll need a Forecast account, first of all. Then you grab an API key for each app you want to build from the Forecast "Admin" section.
We recommend that you start out by getting to know the concepts and conventions of Forecast (and the API) and learn how to authenticate with us.
All URLs start with https://api.forecast.it/api/v1/. SSL only. The path contains the API version. If we change the API in backward-incompatible ways, we'll increment the version marker and maintain stable support for the old URLs.
To make a request for all the projects on your account, you'd append the projects index path to the base url e.g. https://api.forecast.it/api/v1/projects
Using curl it will look like this:
curl -X GET "https://api.forecast.it/api/v1/projects" -H "X-FORECAST-API-KEY: {API-key}"That's it. Super simple, eh?
If you're making a private integration with Forecast for your own purposes, you can use HTTP header "X-FORECAST-API-KEY". This is secure since all requests in Forecast use SSL.
API keys are generated in the administration module.
API keys provide full access to your Forecast account, so keep them like a secret.
If you're worried that an API key has been compromised, or you're simply no longer using the integration that was accessing your account through a particular API key, Forecast makes it possible to disable or delete that API key.
API keys grant full access to your Forecast account, and should be protected the same way you would protect your password. In particular, there are a few common scenarios to keep in mind when working with API keys:
- Give each integration its own API key (or at least use a few). If a specific API key is compromised, you can disable that key without disabling access to all of your other integrations.
- Be careful not to expose the key to the public (such as in screenshots, videos, help documentation, source control, etc). Remember that blurring your data isn't always enough. It's best to use "cut" functions in your graphics program to remove the data completely.
- If a key needs to be shared, generate a new key so it can be disabled, if needed. Make sure never to email the API key; if your email account becomes compromised, the emailed key would allow hackers access to your Forecast account as well.
We only support JSON for serialization of data. This means that you have to send Content-Type: application/json; charset=utf-8 when you're POSTing or PUTing data into Forecast. All API URLs only accept and return JSON.
You'll receive a 415 Unsupported Media Type response code if you don't include the Content-Type header.
All GET requests return 200 OK on success along with the JSON of the requested elements (See specific resource entry for JSON examples).
Successful POST requests return 201 CREATED, and successful PUT requests return 200 OK.
Successful PUT and POST requests also return the JSON of the created/updated resource similar to what you would get from a GET request for that specific resource.
Successful DELETE requests return 200 OK
For endpoints with pagination, you can supply the following query parameters:
| Pagination param | Description/Format |
|---|---|
| pageNumber | Positive integer. Defaults to 1 if not supplied or invalid. |
| pageSize | Positive integer. Defaults to 100. Maximum value is subject to change. |
Responses from paginated endpoints will be in the following format:
| Response fields | Description/Format |
|---|---|
| pageNumber | Positive integer. Page number returned. |
| pageSize | Positive integer. Page size used to generate response. |
| totalObjectCount | Positive integer. Size of the total collection of which this page was returned. |
| pageContents | Array of the objects on the requested page. |
If Forecast is having trouble, you might see a 5xx error. 500 means that the app is entirely down, but you might also see 502 Bad Gateway, 503 Service Unavailable, or 504 Gateway Timeout. It's your responsibility in all of these cases to retry your request later.
400 Errors usually means that the provided input is invalid and the message will tell you what the problem is.
401 is a failure to authenticate the api key.
404 Errors usually means that you are trying to GET/POST/PUT/DELETE a resource that doesn't exist.
Errors are returned in the following JSON format.
| Response Fields | Description/Format |
|---|---|
| status | Integer, the status code of the error. This corresponds to the HTTP status code |
| message | String, a descriptive message explaining the error |
{
"status": 401,
"message": "Server failed to authenticate the request."
}- Allocations
- Baseline Expenses
- Baseline Roles
- Clients
- Company contacts
- Company
- Connected projects
- Deleted data
- Deleted tasks
- Deleted time registrations
- Departments
- Exchange rates
- Expense categories
- Expense items
- Financials
- Holiday calendar entries
- Holiday calendars
- Invoices
- Labels
- Milestones (Deprecated - Name changed to Phases)
- Non project time
- Person cost periods
- Person labels
- Persons
- Person notification settings
- Phases
- Placeholder allocations
- Placeholders
- Priority levels
- Profiles
- Programs
- Project team
- Projects
- Rate card rates
- Rate card versions
- Rate cards
- Repeating tasks
- Roles
- Skill levels
- Skill persons
- Skills
- Sprints
- Sub tasks
- Task Financials
- Tasks
- Teams
- Time registrations
- Webhook subscriptions
- Workflow columns
- Google APIs Client Library - Java
- Jersey - Java
- Feel free to add libraries for other languages :)
Please tell us how we can make the API better. If you have a specific feature request or if you've found a bug, please contact us.
You can always reach us via email at info@forecast.it