> ## Documentation Index
> Fetch the complete documentation index at: https://docs.critique-labs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Build agentic search endpoints with an agent

> Turn one research task into a fully functioning, hosted search endpoint with structured output and cited sources

Critique API is the all-in-one agentic search endpoint builder. Give a coding
agent one natural-language research task and it can create a fully functioning,
hosted endpoint with live web search, source retrieval, citations, structured
JSON, and a callable contract.

Critique handles the search crawler, retrieval pipeline, model workflow,
structured-output layer, and endpoint deployment. The agent creates the
endpoint, reads the server-returned schemas and examples, calls it immediately,
and integrates it into your project with ordinary HTTPS.

## Set up your agent

<Steps>
  <Step title="Create an API key">
    Create a key under [Billing & API Keys](https://critique-labs.ai/en/billing),
    then make it available to your coding agent as an environment variable.

    ```bash theme={null}
    export CRITIQUE_API_KEY="your-api-key"
    ```

    Never paste the key into a prompt, source file, URL, or commit.
  </Step>

  <Step title="Open agent setup">
    Open [API Studio](https://critique-labs.ai/en/design) and select
    **Set up an agent** beside the manual API description form.

    * **Copy prompt** copies the current, server-provided integration prompt
      (select **Show prompt** to read it before copying). Paste it into any
      agent chat; it works without installing anything.
    * **Copy & open ChatGPT** or **Copy & open Claude** copies the prompt and
      opens a new chat.
    * **Use it in Claude Code, Cursor or Codex** shows, per tool, the one-line
      install (`npx skills add …` or the Claude Code plugin commands) and how to
      invoke the skill.
    * **Documentation your agent can read** links the LLM documentation index,
      the full-documentation bundle, this guide, and the OpenAPI contract.

    A browser chat can help plan the endpoint, but it still needs a connected
    tool or coding environment that can read `CRITIQUE_API_KEY` and make HTTPS
    requests in order to create or run one.
  </Step>

  <Step title="Give the agent your requirement">
    Describe the reusable behavior, required inputs, exact output fields,
    freshness requirements, and preferred sources. For example:

    > Create a private API that accepts a company name and returns its latest
    > funding round, amount, date, investors, and primary-source URLs. Then show
    > me how to call it from this project.
  </Step>
</Steps>

## Use the skill without a CLI

The skill works through ordinary authenticated HTTPS requests. It can use
`curl`, JavaScript `fetch`, an IDE HTTP tool, or the existing HTTP client in any
project language. Python and the Critique CLI are not required.

The agent reads the lifecycle contract from the skill, sends
`X-API-Key: $CRITIQUE_API_KEY`, and uses the `integration` object returned by
the server as the source of truth for running the new endpoint.

## Install the CLI (optional)

The optional, open-source CLI package is `critique-api-cli` and has no third-party
runtime dependencies. Its source is available on
[GitHub](https://github.com/parthh01/critique-api-cli).

```bash theme={null}
pipx install critique-api-cli
critique-api --help
```

The CLI is a standalone convenience for terminal workflows. It does not need to
be installed into the user's application or added to that project's
dependencies. After setting `CRITIQUE_API_KEY`:

```bash theme={null}
critique-api create \
  --prompt "For a company name, return its latest funding round, investors, date, amount, and primary-source citations."
```

## Install the skill

The skill lives in the public
[`parthh01/critique-api-cli`](https://github.com/parthh01/critique-api-cli)
repository. Install it into Claude Code, Cursor, Codex or any other agent
supported by [skills.sh](https://skills.sh) with one command (it writes the
skill into each tool's own skills directory; add `-g` to install for all
projects instead of the current one):

```bash theme={null}
npx skills add parthh01/critique-api-cli -y
```

Or install it as a Claude Code plugin from the repo's marketplace:

```text theme={null}
/plugin marketplace add parthh01/critique-api-cli
/plugin install critique@critique-labs
```

| Tool | Install | Invoke |
| - | - | - |
| Claude Code | the two `/plugin` commands above, or `npx skills add parthh01/critique-api-cli -a claude-code -y` | `/critique:create-critique-apis` (plugin) or `/create-critique-apis` (skill) |
| Cursor | `npx skills add parthh01/critique-api-cli -a cursor -y` | Type `/` in Agent chat and pick the skill |
| Codex | `npx skills add parthh01/critique-api-cli -a codex -y` | `$create-critique-apis` |

Each tool also applies the skill automatically when a task matches its
description. Make sure `CRITIQUE_API_KEY` is exported in the shell the agent
runs in.

The integration prompt, these per-tool commands (`clients`), and the resource
URLs are also available without authentication for automated discovery; the raw
skill files remain downloadable as a zip for agents that fetch them directly:

```bash theme={null}
curl --fail-with-body https://api.critique-labs.ai/v1/agent-integration
```

## Documentation for agents

This documentation is written to be read by LLMs as well as people:

* [`llms.txt`](https://docs.critique-labs.ai/llms.txt) is the index of every
  page. Agents should fetch it first when they need something a prompt does not
  cover.
* Every page is available as Markdown: append `.md` to a page URL that does not
  already end in `.md` (this page is
  `https://docs.critique-labs.ai/api-platform/agent-created-apis.md`).
* [`llms-full.txt`](https://docs.critique-labs.ai/llms-full.txt) bundles every
  page into one file, each prefixed with a `Source:` line, for a single fetch.
* [`openapi.json`](https://api.critique-labs.ai/openapi.json) is the
  machine-readable contract for every endpoint.

## Endpoint lifecycle

All management and runtime requests use the `X-API-Key` header. These examples
assume `CRITIQUE_API_KEY` is set in the environment.

### Create

The only required create field is `original_prompt`.

```bash theme={null}
curl --fail-with-body --request POST \
  https://api.critique-labs.ai/v1/design-api \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $CRITIQUE_API_KEY" \
  --data '{
    "original_prompt": "For a company name, return its latest funding round, investors, date, amount, and primary-source citations."
  }'
```

The response is wrapped in `response`. Treat `response.integration` as the
authoritative handoff: it contains the final callable URL, authentication
contract, request and response JSON Schemas, an example request, runnable code,
and a short agent handoff.

```json theme={null}
{
  "response": {
    "id": 42,
    "api_name": "Latest company funding",
    "stub": "latest-company-funding",
    "inputs": [{ "name": "company", "type": "string" }],
    "output_format": {
      "company": "string",
      "amount": "number",
      "date": "string",
      "investors": [{ "name": "string" }]
    },
    "integration": {
      "method": "POST",
      "url": "https://api.critique-labs.ai/v1/user-defined-service/latest-company-funding",
      "request_schema": {},
      "response_schema": {},
      "example_request": { "company": "<company>" },
      "code": {
        "curl": "...",
        "python": "...",
        "javascript": "..."
      },
      "agent_handoff": "..."
    }
  }
}
```

<Note>
  Do not construct the runtime URL from the stub when an `integration.url` is
  available. The server-returned integration object is the source of truth.
</Note>

### Inspect and modify

```bash theme={null}
# List your private endpoints
curl --fail-with-body \
  --header "X-API-Key: $CRITIQUE_API_KEY" \
  https://api.critique-labs.ai/v1/design-api

# Inspect one endpoint
curl --fail-with-body \
  --header "X-API-Key: $CRITIQUE_API_KEY" \
  https://api.critique-labs.ai/v1/design-api/42

# Send only the fields that should change
curl --fail-with-body --request PATCH \
  https://api.critique-labs.ai/v1/design-api/42 \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $CRITIQUE_API_KEY" \
  --data '{
    "inputs": [
      { "name": "company", "type": "string", "required": true, "default": null },
      { "name": "region", "type": "string", "required": false, "default": null },
      { "name": "max_results", "type": "number", "required": false, "default": 10 }
    ],
    "output_format": {
      "company": "string",
      "amount": "number",
      "announced": "boolean",
      "investors": [{ "name": "string" }]
    }
  }'
```

Input names must begin with a letter or underscore and may contain letters,
numbers, and underscores. Supported input types are `string`, `number`, and
`boolean`. Output formats support nested objects and one-item array schemas in
addition to `string`, `number`, `boolean`, and `integer` values.

#### Optional inputs and defaults

Each input carries `required` (default `true`) and `default` (default `null`).
Inputs created before these keys existed are required with no default, and
nothing about them changed.

* A non-null `default` must match the input's `type` and makes the input
  optional whatever `required` says.
* Callers may omit any optional input (sending `null` counts as omitting it).
  The endpoint fills in the default, or,
  when the default is `null`, tells the agent the value was not provided.
* A missing required input responds `400`; the message lists only the missing
  required fields, with optional ones shown as `name?: type`.
* `integration.request_schema` marks only required inputs as required and
  carries each default; `integration.example_request` and the code samples
  include every required input plus every optional input that has a default.

`max_results` is a reserved input name. An endpoint whose output contains a
list is created with an optional `max_results` (type `number`, default `10`);
the runtime asks the agent for at most that many items and caps every top-level
list field of the response at that value (nested lists are left to the agent).
The value must be a number of at least 1 and is floored to an integer.

### Versions

Every endpoint version is its own resource with its own `id`; all versions share
the endpoint's `stub`. A version is a **draft** while `frozen_at` is `null`
(editable; at most one per endpoint) and **released** once `frozen_at` is set
(immutable; edits respond `409`). The **live** version is what the unversioned
URL `/v1/user-defined-service/{stub}` runs: the released version with the
highest number, or the only draft when nothing has ever been released, which is
the normal state of a freshly created endpoint. Every response carries
`version`, `frozen_at`, `is_live`, `live_version` and a `versions` list for the
whole lineage.

```bash theme={null}
# Release the current draft: it becomes immutable and live
curl --fail-with-body --request POST \
  --header "X-API-Key: $CRITIQUE_API_KEY" \
  https://api.critique-labs.ai/v1/design-api/42/release

# Create the next version: copies v42 into a new editable draft
curl --fail-with-body --request POST \
  https://api.critique-labs.ai/v1/design-api/42/versions \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $CRITIQUE_API_KEY" \
  --data '{"version_notes": "added the funding_stage output field"}'

# List the lineage; add ?all_versions=true to GET /v1/design-api for every version
curl --fail-with-body \
  --header "X-API-Key: $CRITIQUE_API_KEY" \
  https://api.critique-labs.ai/v1/design-api/42/versions
```

If the version you copy is the current draft it is released first, so callers on
the unversioned URL keep the behaviour they tested. Creating a version while
another unreleased draft exists responds `409`: release or delete that draft
first. Publishing a version to the marketplace also releases it. Creating a
version from an older released one is how you revert; the copy becomes live
once you release it.

Always call `integration.url`. For the live version it is the unversioned URL;
for a draft that is not live, and for an older release, it is the pinned URL
`/v1/user-defined-service/{stub}/v{n}`, the only URL that runs that version.
`integration.versioned_url` is always the pinned URL. A pinned version that does
not exist responds `404`.

### Run

POST a body matching `integration.request_schema` to `integration.url`:

```bash theme={null}
curl --fail-with-body --request POST \
  https://api.critique-labs.ai/v1/user-defined-service/latest-company-funding \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $CRITIQUE_API_KEY" \
  --data '{ "company": "OpenAI" }'
```

A successful runtime response contains the structured result, its source list,
and usage information:

```json theme={null}
{
  "response": {
    "company": "OpenAI",
    "amount": 6600000000,
    "date": "2024-10-02",
    "investors": [{ "name": "Thrive Capital" }]
  },
  "context": [
    {
      "id": 1,
      "metadata": {
        "title": "Source title",
        "url": "https://example.com/source",
        "content": "Relevant source content"
      }
    }
  ],
  "info": { "token_usage": 123 }
}
```

Preserve `context` when displaying or storing researched output so its source
URLs remain available to users.

### Delete

Deletion is permanent. Confirm the endpoint ID before calling:

```bash theme={null}
curl --fail-with-body --request DELETE \
  --header "X-API-Key: $CRITIQUE_API_KEY" \
  https://api.critique-labs.ai/v1/design-api/42
```

## Optional domain controls

Runtime bodies may include `include_domains` or `exclude_domains` as an array of
domain strings. They are mutually exclusive.

```json theme={null}
{
  "company": "OpenAI",
  "include_domains": ["openai.com", "sec.gov"]
}
```

## Error handling

* `400` or `422`: correct the request or schema; do not retry unchanged.
* `401`: verify that `CRITIQUE_API_KEY` is available without printing it.
* `404`: list endpoints and confirm that the ID belongs to the current key. On
  a `/v{n}` invocation, confirm the version exists with
  `GET /v1/design-api/{id}/versions`.
* `409`: the version is released (immutable) or the endpoint already has an
  unreleased draft. Create or release a version instead of retrying.
* `429`: respect the rate limit before retrying.
* `504`: the research request exceeded the service deadline.

See [API rate limits](/api-reference/rate-limits) for current plan limits.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.