Open API

Need to query workspaces in Teamhood? Here’s a quick example to get you started. This is an essential first step because you’ll need workspace IDs to manage items or boards effectively.

Open API set up

To start working with Teamhood API, you need a couple of things:

1. Private API key
2. A dedicated API URL for your company account

You can find both by navigating to the settings page Company Account -> Integrations.

Account keys vs. workspace keys

API access can be configured at two levels:

• The account API key above reaches data across the whole company account.
• Each workspace also has its own workspace API key. The Workspace API can only reach data inside that one workspace, which keeps integrations separated and easier to manage — and limits the blast radius if a key is ever exposed.

The workspace key is available to workspace Admins on the Workspace Integrations page. If you are looking for it under Workspace settings → General, note that it moved when the Workspace Integrations interface was reworked.

Copy the API key and click on API Documentation. You will be navigated to the Swagger specification. Click Authorize to supply the APIKey and start interacting with the Teamhood API.

Working with Teamhood’s API

You will most likely need to start by querying available workspaces to get their IDs. You will use the workspace ID in other queries for items or boards.

For example, you can use the API to automate tasks in a marketing campaign or track time spent on software development projects. This helps save time and keeps your team on the same page.

⚒️ Examples

• Code examples on how to use Open API

Quick examples

Query Teamhood api for workspaces

Bash script

curl -X GET \
  'https://TEAMHOOD_API/api/v1/workspaces' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json'

Powershell

$apiToken = "YOUR_API_KEY"
$headers = @{
    "Authorization" = "$apiToken"
    "Content-Type" = "application/json"
}
$response = Invoke-RestMethod `
    -Uri "https://TEAMHOOD_API/api/v1/workspaces" `
    -Method Get `
    -Headers $headers

Managing items

⚠️ Some methods, such as Item queries, have a result limit for 1000 items. If there are more, you will need to use paging. API contains skip and take parameters for that.

Board structure

To get the structural elements of the board, you will need to use Board ID as the main parameter and then the following two queries for rows and statuses:

⚠️ Statuses query does not return status groups but a flat list of board statuses instead.

Item color codes

Teamhood uses color-agnostic coding for items to support light and dark themes. Here is a map of integer to color values.

“1” – No color or light gray
“2” – Yellow
“3” – Coral
“4” – Brown
“5” – Red
“6” – Pink
“7” – Violet
“8” – Blue
“9” – Cyan
“10” – Green
“11” – Orange
“12” – Moss
“13” – Teal
“14” – Purple
“15” – Plum
“16” – Rose
“17” – Gray
“18” – Cerulean

Troubleshooting

1. Ensure you are using the correct Teamhood API address, which is unique for each company account
2. Ensure you are using the correct ApiKey
3. Test API methods via Swagger first to see what data they return
4. Ensure you have the right subscription plan necessary for API access

Teamhood API Capabilities

Teamhood API allows you to:

• Create work items
• Complete work items
• Update items
• Create boards
• Create rows
• Create workspaces
• Invite users into workspaces
• Read and extract item-related data
• Read board structure data
• Read user list
• Read time logs
• Set relations between items, so dependencies can be created programmatically
• Create synced copies of items
• Update the Budget field, to sync figures from an external system
• Read item activity logs and flow metrics from a dedicated endpoint
• Read baseline data, returned as part of the existing GET items request
• Read the last activity date for each user, via the User API

Explore our Knowledge Base for a deeper dive into available methods and integration tips.

Aggregated Values in Responses

Item queries return aggregated values directly in the response, so you do not have to walk the child items and total them up yourself. Aggregation is supported for:

• start date and due date
• progress
• estimation and tracked time
• budget
• numeric custom fields

Item responses also include the RowRank value, which tells you where an item sits in its row ordering.

💡 If you are reaching for the API purely to update items when something changes inside Teamhood, check Automations first — it may remove the need for an integration altogether.