> For the complete documentation index, see [llms.txt](https://docs.uptiq.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uptiq.ai/cookbooks/readme.md).

# Overview

Run UPTIQ platform administration heedlessly with ordered API workflows.

Cookbooks are API workflows for platform tasks. Use them to automate administration without the Control Center.

Every call belongs to a microservice. The service path is part of its URL.

{% hint style="info" %}
**Start with Platform Admin.** It covers account setup, access, models, costs, and agent operations.
{% endhint %}

<details>

<summary>Run evidence and next steps</summary>

Check this page's evidence notes before automating it. A **Verified against QA** note records live behavior and its test date. Other request and response details are specification-checked unless stated otherwise.

Before each repeat run:

1. Confirm the tenant URL, credential type, and required identifiers.
2. Record the status code and response shape.
3. Compare the result with this recipe. Update its evidence note when behavior differs.

> Don't treat a successful request as proof of the intended state. Use the response and follow-up guidance before continuing.

</details>

## What you need

| Value              | Why you need it                                    | Where to get it                                                       |
| ------------------ | -------------------------------------------------- | --------------------------------------------------------------------- |
| Tenant service URL | Routes a call to the correct microservice          | Choose the QA or production environment                               |
| API key            | Authenticates every request                        | Create one in the platform or with `POST /api-keys`                   |
| Account ID         | Scopes account-level calls                         | Save `data.id` from `POST /accounts`, or copy the existing account ID |
| Project or app ID  | Scopes agent calls when that operation requires it | Retrieve it from the target project or app                            |

Send the API key with `authorization: Bearer YOUR_API_KEY`. Send `accountid` for Identity Hub and Agent Builder calls.

## Start in this order

{% stepper %}
{% step %}

#### Choose the tenant service URL

Use the correct environment and service path. For QA, Identity Hub calls start at `https://api-builder-qa.uptiq.dev/identity-hub`.
{% endstep %}

{% step %}

#### Establish account context

Create an account with `POST /accounts` only when you are an organization administrator. Save its returned ID.
{% endstep %}

{% step %}

#### Create a scoped API key

Call `POST /api-keys` with an existing administrative credential. Store the returned secret immediately.
{% endstep %}

{% step %}

#### Configure the account

Set a credit limit first. Then configure the model family and provider credentials.
{% endstep %}

{% step %}

#### Automate the task

Use the endpoint catalog in each Platform Admin area. Each row names its microservice and endpoint.
{% endstep %}
{% endstepper %}

{% columns %}
{% column %}

#### Start with a workflow

Choose a role, then find the task you need to automate. Each workflow focuses on one outcome.
{% endcolumn %}

{% column %}

#### Build against the API

Use the request examples, inputs, and response details in each workflow to integrate with the platform.
{% endcolumn %}
{% endcolumns %}

## A cookbook contains

| Unit              | Purpose                                               |
| ----------------- | ----------------------------------------------------- |
| **Goal**          | The task the workflow completes                       |
| **Prerequisites** | Required permissions, IDs, credentials, and setup     |
| **Request**       | Endpoint, method, fields, and ready-to-adapt examples |
| **Response**      | Expected status, returned data, and values to retain  |
| **Notes**         | Constraints, follow-up calls, and known API gaps      |

## Browse by role

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-user-shield" style="color:$primary;">:user-shield:</i></td><td><strong>Platform Admin</strong><br>Manage accounts, access, API keys, models, costs, and agent activity.</td><td><a href="/cookbooks/platform-admin.md">Platform Admin</a></td></tr></tbody></table>

{% hint style="info" %}
**More role-based cookbooks are planned.** This collection currently covers Platform Admin workflows.
{% endhint %}

{% hint style="warning" %}
**QA service URLs:** The gateway base is `https://api-builder-qa.uptiq.dev`. Add the service path, such as `/identity-hub` or `/agent-builder`. Use the production tenant URL for shipped work.
{% endhint %}

{% hint style="info" %}
**Evidence status varies by recipe.** Every endpoint, method, and request field is checked against the OpenAPI documents in `api-references/qa/api-reference/specs/`. Recipes that were also run against QA say so and include the verification date. If a response shape differs, record it and update the recipe's evidence note.
{% endhint %}

## API references

* [Authentication reference](https://gitlab.com/uptiq-inc-enterprise/development/documentation/platform-docs-repo/-/tree/main/api-references/qa/getting-started/authentication.md)
* [API reference](https://gitlab.com/uptiq-inc-enterprise/development/documentation/platform-docs-repo/-/tree/main/api-references/qa/api-reference/README.md)


---

# 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.uptiq.ai/cookbooks/readme.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.