---
title: "OpenAPI Spec & TypeScript Clients"
description: "Machine-readable OpenAPI 3.1.0 spec for the Minds API. Generate typed TypeScript clients or pipe the JSON straight into your LLM."
---

# OpenAPI Spec

The Minds public API ships a machine-readable OpenAPI 3.1.0 spec. Build typed clients or give the JSON to an LLM for routes with detailed operation metadata. Use the [complete endpoint catalog](/docs/api/reference) alongside it while schema coverage is expanded.

## Endpoint

<table>
<thead>
  <tr>
    <th>
      URL
    </th>
    
    <th>
      What you get
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        https://getminds.ai/_openapi.json
      </code>
    </td>
    
    <td>
      OpenAPI 3.1.0 JSON spec. Feed this into any generator.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        https://getminds.ai/_openapi-3.0.json
      </code>
    </td>
    
    <td>
      Generated OpenAPI 3.0.2 compatibility view for importers such as RapidAPI.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        https://getminds.ai/api/v1/openapi.json
      </code>
    </td>
    
    <td>
      The same spec, served next to the endpoints it describes. No API key needed.
    </td>
  </tr>
</tbody>
</table>

Both documents come from the same route metadata. The 3.1 document is canonical. The generated 3.0.2 view only exists for importers that do not support 3.1. Both include only public `/api/v1/**` endpoints that declare OpenAPI metadata. Internal endpoints (admin, debug, cron, MCP, etc.) are excluded.

## Authentication

Every operation in the spec is gated by `ApiKeyAuth` — send your personal API key as a bearer token:

```http
Authorization: Bearer minds_…_key
```

Create one in [Settings → API Keys](/settings/api-keys). See [Authentication](/docs/api/authentication) for the full flow.

## Generate a TypeScript client

The fastest path: use [`openapi-typescript`](https://openapi-ts.dev/) to generate strict types from the live spec.

```bash
npx openapi-typescript https://getminds.ai/_openapi.json -o minds.d.ts
```

Then use them with `openapi-fetch` for a fully-typed client:

```ts
import createClient from 'openapi-fetch'
import type { paths } from './minds'

const client = createClient<paths>({
  baseUrl: 'https://api.getminds.ai',
  headers: { Authorization: `Bearer ${process.env.MINDS_API_KEY}` },
})

// All params + responses are typed from the live spec.
const { data, error } = await client.GET('/api/v1/minds', {
  params: { query: { limit: 10 } },
})
```

Prefer a runtime SDK? Any OpenAPI 3.1-compatible generator works — [`openapi-generator`](https://openapi-generator.tech/), [`orval`](https://orval.dev/), [`kubb`](https://www.kubb.dev/), etc.

## Use it with an LLM

The JSON spec is small enough to drop into a chat:

```bash
curl -s https://getminds.ai/_openapi.json | pbcopy
```

Then paste it into ChatGPT, Claude, Cursor, or another coding agent with a prompt like:

> Here is the Minds API OpenAPI spec. Also consult [https://getminds.ai/api/reference](https://getminds.ai/docs/api/reference) and [https://getminds.ai/api/agents](https://getminds.ai/docs/api/agents). Write a Python script that lists my Minds and prints their IDs and names. Read the API key from `MINDS_API_KEY`; never print it.

The spec includes the bearer-token contract and operation metadata for covered routes. The endpoint catalog supplies complete route discovery, while the domain pages provide richer workflow examples and limitations.

## Coverage

The spec lists only `/api/v1/**` endpoints that opt in via `defineRouteMeta({ openAPI: … })`. It deliberately excludes internal admin, cron, debug, app-only, and MCP routes. Detailed v1 schema coverage is progressive: absence from the spec does not mean a v1 route is unavailable. The [endpoint catalog](/docs/api/reference) is tested against every concrete v1 route and is the completeness authority.

> **Note on stability:** OpenAPI generation runs on Nitro's experimental `openAPI` flag. The spec format is stable (OpenAPI 3.1.0); minor structural drift in operation metadata is possible as the underlying Nitro feature matures. Pin your client-generation step to a build artifact if you need a frozen contract.

## Next steps

- Fetch the live spec at [/_openapi.json](/_openapi.json)
- Read [Authentication](/docs/api/authentication) for the bearer-token flow
- Browse the [complete endpoint catalog](/docs/api/reference)
- Follow the [API integration guide for agents](/docs/api/agents)
- Jump into [Minds](/docs/api/minds), [Studies](/docs/api/studies), or [Chat](/docs/api/chat) for endpoint walkthroughs