How the Teamhood API works
The Teamhood API lets a script or a service read and change the work in one organization over HTTP. Every request carries a personal token, and acts as the person who created that token. The API reference lists every request, with its fields and an example.
Settings → API opens the reference for your organization. Open in Teamhood
The address of your organization
Section titled “The address of your organization”Every request goes to an address that includes the name of your organization:
https://api.teamhood.com/public/v1/<organization name>/The name is the part after app.teamhood.com/ in the address you see in the app. In app.teamhood.com/acme/inbox the name is acme.
Signing in with a personal token
Section titled “Signing in with a personal token”Send a token from Personal tokens in the X-Api-Key header of every request. The API accepts no other way to sign in.
A token works only in the organization where it was created. A token sent to another organization is refused as if it did not exist.
A token can do exactly what its owner can do. When the role of the owner does not allow a change, the API refuses the change. Items of a type the owner cannot read are left out of lists.
An organization can require two-factor authentication. Then the owner of the token must have it set up. Otherwise every request is refused.
Items, types and fields
Section titled “Items, types and fields”Everything you plan is an item, and every item has a type. One address serves the items of every type. A new item names its type by the key of the type.
The values of an item are in fields. Each value is named by the key of its field. The key is not the name you see on screen, and keys differ between organizations. So a script reads the types and their fields first.
- A change names only the values it changes. Values left out stay as they are.
- A value of
nullremoves that value. - A field key the type does not have is refused.
- A value for a read-only field is ignored.
- The type of an item cannot be changed.
An example
Section titled “An example”A script gives an estimate to every task that has none, in an organization named acme. First it reads the fields of tasks with GET /public/v1/acme/types/task/fields. It learns that the estimate field has the key storyPoints.
The script then asks for the tasks that have no estimate: GET /public/v1/acme/items?type=task&fields[storyPoints][exists]=false. For each task, it sends PATCH /public/v1/acme/items/<id> with the body {"fields": {"storyPoints": 3}}. Only the estimate changes.
Each task’s activity shows the change under the name of the token owner, with the API label.
How much you can send
Section titled “How much you can send”- Each organization can send 200 requests a minute. All tokens of the organization share that limit. A request over the limit is refused, and the
Retry-Afterheader says how many seconds to wait. - A list of items returns 50 items unless the request asks for more with
limit. The most it returns is 200. - An attached file can be at most 100 MB.
Reading every page of a list
Section titled “Reading every page of a list”An answer that has more items carries a nextCursor. Send it back as cursor to get the next page. Stop when an answer has no cursor or no items. A last page that is exactly full still carries a cursor, and that cursor returns an empty page.
In the example above, the script reads every page before it changes a task. A task that gets an estimate leaves the list, and the pages still to come would then skip tasks.
When a request is refused
Section titled “When a request is refused”Most refusals carry a body that says why. The API reference lists every status. These are the ones that surprise people:
| Status | Meaning |
|---|---|
401 | Token from another organization, or owner no longer active |
402 | Subscription of the organization lapsed |
403 | Change the role does not allow, or two-factor authentication missing |
404 | Item of a type the owner cannot read |
A lapsed organization answers every request with 402 until its subscription is restored. See What happens when a subscription lapses.
Things that are easy to miss
Section titled “Things that are easy to miss”- Deleting an item moves the item and everything under it to the trash. Items under it that were archived separately stay in the archive. The app can restore the item for 30 days. The API cannot restore an item.
- When the owner may not delete one of the items under it, nothing is deleted.
- The history of changes is read one item at a time. To find the items that changed, ask for items with
updatedSince. Deleted items are not in that list. - To hear about changes as they happen, use Webhooks.