GitLab Installations API

These endpoints allow you to manage GitLab installations, repositories, and work manifests within Terrateam.

List GitLab Installations

Get all GitLab installations.

Endpoint: GET /api/v1/gitlab/installations

Responses:

• 200: Success - Returns installations
• 403: Forbidden

Response Schema (200):

{
  "installations": [...]
}

---

Create Access Token

Create or update an access token for a GitLab installation.

Endpoint: PUT /api/v1/gitlab/installations/{installation_id}/access-token

Path Parameters:

Name	Type	Required	Description
installation_id	string	Yes	The installation identifier

Request Body:

Content-Type: application/json

Schema: gitlab-access-token

Responses:

• 200: Success
• 403: Forbidden

Example Request:

curl -X PUT \
  https://app.terrateam.io/api/v1/gitlab/installations/{installation_id}/access-token \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{...}'

---

List Dirspaces

Retrieve directory-workspace pairs (dirspaces) for a GitLab installation.

Endpoint: GET /api/v1/gitlab/installations/{installation_id}/dirspaces

Path Parameters:

Name	Type	Required	Description
installation_id	string	Yes	The installation identifier

Query Parameters:

Name	Type	Required	Description
page	array[string]	No	Pagination token
q	string	No	Search query
d	string	No	Sort direction: asc or desc
tz	string	No	Timezone for date filtering
limit	integer	No	Maximum number of results

Responses:

• 200: Success - Returns dirspaces list
• 400: Bad Request
• 403: Forbidden

Response Schema (200):

{
  "dirspaces": [...]
}

---

List Repositories

Retrieve repositories for a GitLab installation.

Endpoint: GET /api/v1/gitlab/installations/{installation_id}/repos

Path Parameters:

Name	Type	Required	Description
installation_id	string	Yes	The installation identifier

Query Parameters:

Name	Type	Required	Description
page	array[string]	No	Pagination token

Responses:

• 200: Success - Returns repositories
• 403: Forbidden

Response Schema (200):

{
  "repositories": [...]
}

---

List Work Manifests

Retrieve work manifests for a GitLab installation.

Endpoint: GET /api/v1/gitlab/installations/{installation_id}/work-manifests

Path Parameters:

Name	Type	Required	Description
installation_id	string	Yes	The installation identifier

Query Parameters:

Name	Type	Required	Description
page	array[string]	No	Pagination token
q	string	No	Search query
d	string	No	Sort direction: asc or desc
tz	string	No	Timezone for date filtering
limit	integer	No	Maximum number of results

Responses:

• 200: Success - Returns work manifests
• 400: Bad Request
• 403: Forbidden

Response Schema (200):

{
  "work_manifests": [...]
}

---

Get Work Manifest

Retrieve a specific work manifest by ID.

Endpoint: GET /api/v1/gitlab/installations/{installation_id}/work-manifests/{work_manifest_id}

Path Parameters:

Name	Type	Required	Description
installation_id	string	Yes	The installation identifier
work_manifest_id	string	Yes	The work manifest identifier

Responses:

• 200: Success - Returns work manifest details
• 403: Forbidden
• 404: Not Found

---

Get Work Manifest Outputs

Retrieve outputs and steps for a work manifest.

Endpoint: GET /api/v1/gitlab/installations/{installation_id}/work-manifests/{work_manifest_id}/outputs

Path Parameters:

Name	Type	Required	Description
installation_id	string	Yes	The installation identifier
work_manifest_id	string	Yes	The work manifest identifier

Query Parameters:

Name	Type	Required	Description
q	string	No	Search query
page	array[string]	No	Pagination token
tz	string	No	Timezone for date filtering
limit	integer	No	Maximum number of results
lite	boolean	No	Return lightweight response (default: false)

Responses:

• 200: Success - Returns workflow step outputs
• 400: Bad Request
• 403: Forbidden
• 404: Not Found

Response Schema (200):

{
  "steps": [...]
}

---

Authentication

All endpoints require authentication using a short-lived access token:

Authorization: Bearer YOUR_ACCESS_TOKEN

To get an access token:

1. Create an API key in Settings > API Access in the Terrateam dashboard
2. Call POST /api/v1/access-token/refresh with your API key to get an access token
3. Use the access token for API requests

See the Authentication guide for detailed instructions.