> For the complete documentation index, see [llms.txt](https://docs.contextual.io/documentation-and-resources/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/services-api.md).

# Services API

Read and manage Services, their components, releases, and installations.

The Services API manages the Services in your tenant. A Service packages components, such as Object Types, Agents, and Connections, at pinned versions. You release a Service in one tenant and install the release in another.

It is for solution developers and administrators. The Console and the CLI's `ctxl services` and `ctxl servicereleases` commands also use it. In the Admin Console, under **Build > Services**, you create releases and install and update Services.

## What you can do

* List and read Services, their components, and their releases. Compare a Service's components with its latest release.
* Create, change, and delete Services. Add and remove components, and change their pinned versions.
* Create a release, which keeps the Service's current component versions. Change a release's track and notes.
* Install a release from another tenant, and update an installed Service to a newer release. Validate an installation or update before you apply it.

To change a Service's components, use `ctxl services patch`. To install a release or update an installed Service, use **Build > Services** in the Admin Console.

A component is either a **direct** dependency, which the Service creates and owns in the tenant where you install it, or a **peer** dependency, which must already exist there.

A dependency can identify an Object Type definition or a specific record at a pinned version. Including an Object Type definition does not include its records. Add each record explicitly if the Service should manage it; otherwise, plan separate record creation or migration.

Workers deploy independently of Services; deploying a Worker through a Service release is not supported. Use Service releases to deliver any Service-managed prerequisites the Workers need, then deploy the Workers in the target tenant. A deployment pipeline can coordinate both operations. Do not add the Worker record or its platform-created Agent to a Service's components. See [Coordinate Worker Deployments and Service Releases](https://docs.contextual.io/documentation-and-resources/components-and-data/contextual-workers/releases.md).

Updates and deletions change components in the tenant:

* Updating an installed Service makes its direct dependencies match the new release. This overwrites changes made to them in the installed tenant and deletes the ones the new release drops.
* Deleting an installed Service also tries to delete its direct dependencies. Deleting a Service you own leaves its components by default. When `deleteDirectDependencies=true` is set, the API also attempts to delete its direct dependencies. If a component can't be deleted, the Service is still deleted. Check for components left behind.

## Base URL and reference

* **API base URL:** `https://services.<tenant-id>.my.contextual.io/api/v1`
* **Swagger reference:** [Services API reference](https://services.prod-001.prod.contextual.io/api-docs/)
* **Raw OpenAPI:** [openapi.json](https://services.prod-001.prod.contextual.io/api-docs/openapi.json)

Replace `<tenant-id>` with the [tenant ID from your Tenant Workspace URL](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/authentication-and-permissions.md#identify-the-tenant). On the API base URL, the hostname identifies your tenant. Also send `x-org-id: <tenant-id>` with every API call, matching the hostname. Some installation and dependents operations take the tenant from this header.

The OpenAPI document uses the relative server `/api/v1`. When you import it into an API client or AI tool, set the server to the API base URL.

## Authentication and permissions

Send an access token in the `Authorization: Bearer <access-token>` header. [Authentication and Permissions](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/authentication-and-permissions.md) explains credentials, tenant context, and token reuse.

In the Admin Console, you assign Services permissions to Roles. The API Key [Permissions tab](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/authentication-and-permissions.md#assign-permissions) does not offer them.

| Task                                                               | Role permission in the Admin Console     | Permission                           |
| ------------------------------------------------------------------ | ---------------------------------------- | ------------------------------------ |
| List and read Services, components, and releases; compare releases | **Services → Services → Read**           | `contextual:services:read`           |
| Create a Service                                                   | **Services → Services → Create**         | `contextual:services:create`         |
| Change a Service or its components                                 | **Services → Services → Update**         | `contextual:services:update`         |
| Delete a Service                                                   | **Services → Services → Delete**         | `contextual:services:delete`         |
| Create a release                                                   | **Services → Service releases → Create** | `contextual:service-releases:create` |
| Change a release's track or notes                                  | **Services → Service releases → Update** | `contextual:service-releases:update` |
| Install a Service                                                  | **Services → Service installs → Create** | `contextual:service-installs:create` |
| Update an installed Service                                        | **Services → Service installs → Update** | `contextual:service-installs:update` |

Validating an installation or update needs either `contextual:service-installs:create` or `contextual:service-installs:update`.

For operations that fetch or change components, such as creating a release or installing a Service, your Role also needs the matching **Service components** permissions, such as **Object Types** or **Agents**. They apply in the tenant whose components are read or changed.

Installation and update requests, including validation, also need an access token in the request body. That token must be able to read the release in the source tenant.

The permissions to install, update, and delete let a caller add, overwrite, and delete components in a tenant. Grant them only to callers responsible for managing releases.

## Request and response details

* Request and response bodies are JSON.
* List responses return results in `items`. To get the next page, send the returned `nextPageToken` as `pageToken`. Continue until a response has no `nextPageToken`, even if `items` is empty. Set the page size with `pageSize`. To get `totalCount`, add `includeTotal=true` to the first request.
* `GET /services/{id}` omits the Service's components. Add `withDependenciesWithData=true` to include them with their full definitions. The response can be large.
* When you form a request, replace `[\$]` in a reference path with a literal `$`. For example, `/[\$]page/services` becomes `/$page/services`. In a shell command, put a URL that contains `$page` in single quotes, or write `\$page`, so that the shell doesn't replace `$page` with a variable's value.

## Example request

This request lists up to 10 Services:

```bash
curl "https://services.<tenant-id>.my.contextual.io/api/v1/services?pageSize=10" \
  --header "Authorization: Bearer <access-token>" \
  --header "x-org-id: <tenant-id>"
```

Replace `<access-token>` with your access token. A successful response has status `200` and up to 10 Services in `items`. Each Service has an `id`, `name`, `version`, and `_metaData`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/services-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
