api-mind

LLM tools for API discovery from .mind spec files. Works with .mind files generated by spec-mind.

Why

LLMs interacting with HTTP APIs need to discover endpoints, understand contracts, and make requests. api-mind provides 3 tools for discovery and context:

• list_apis - Discover available APIs
• list_endpoints - Find endpoints across APIs
• get_endpoint_schema - Get base URL, auth requirements, and schema

The LLM then constructs and executes curl commands via the bash tool with full transparency.

Installation

Quick Install

# Project-level (recommended)
curl -sSL https://raw.githubusercontent.com/msegoviadev/api-mind/main/install.sh | bash

# Global (user-wide, available for all projects)
curl -sSL https://raw.githubusercontent.com/msegoviadev/api-mind/main/install.sh | bash -s -- --global

The script will:

1. Add @msegoviadev/api-mind to your opencode.json
2. Download API-MIND.md to the appropriate location
3. Add @API-MIND.md reference to your AGENTS.md

Manual Installation

1. Add plugin to your OpenCode config

Add @msegoviadev/api-mind to your opencode.json or opencode.jsonc:

{
  "plugin": ["@msegoviadev/api-mind"]
}

OpenCode will automatically install the plugin from npm on startup.

2. Download the context file

Run this command in your project root:

curl -sSL https://raw.githubusercontent.com/msegoviadev/api-mind/main/API-MIND.md -o API-MIND.md

3. Reference in your AGENTS.md

Add this line to your AGENTS.md:

@API-MIND.md

Setup

1. Place OpenAPI specs in specs/ folder:

   specs/
     api1.yaml
     api2.yaml

2. Generate .mind files using spec-mind:

   spec-mind sync --no-notation ./specs/

3. Commit .mind files alongside source specs:

   specs/
     api1.yaml
     api1.mind   # generated
     api2.yaml
     api2.mind   # generated

4. Tools automatically load from specs/*.mind

Configuration

By default, api-mind looks for .mind files in the specs/ directory.

To customize the specs location, create an api-mind.json file in your project root:

{
  "specsDir": "documentation/api-specs"
}

The path is relative to your project root (where you run opencode).

Tools

list_apis

Lists all APIs loaded from the specs folder.

Input: none
Output: JSON with API names, titles, base URLs, and environments

Call first to discover what APIs are available.

list_endpoints

Lists endpoints across all APIs.

Input:
  filter (optional): Substring match on method, path, or section

Output: JSON with environments and endpoint list

Call to find specific endpoints.

get_endpoint_schema

Returns full context for an endpoint.

Input:
  api: API name
  method: HTTP method
  path: Endpoint path

Output: Text block with base URL, environments, auth, and schema

Call before constructing curl to understand the endpoint.

Workflow

list_apis → list_endpoints → get_endpoint_schema → [LLM constructs curl] → bash

1. list_apis - Discover available APIs
2. list_endpoints - Find relevant endpoints
3. get_endpoint_schema - Get context (URL, auth, schema)
4. LLM constructs curl command with proper URL and headers
5. LLM executes via bash tool

Auth Patterns

When get_endpoint_schema shows auth requirements, construct headers:

| Auth in Schema | curl Header | |----------------|-------------| | None | No header | | bearer | -H 'Authorization: Bearer <TOKEN>' | | oauth2 <scopes> | -H 'Authorization: Bearer <TOKEN>' | | api_key <header> | -H '<header>: <KEY>' | | basic | -H 'Authorization: Basic <base64>' |

Related

• spec-mind - Generate .mind files from OpenAPI specs

Development

Build

bun run build

Test Locally

For local testing without publishing, create a symlink in your test project:

# In your test project
mkdir -p .opencode/plugins
ln -s /path/to/api-mind/src/index.ts .opencode/plugins/api-mind.ts
ln -s /path/to/api-mind/API-MIND.md API-MIND.md

License

MIT