Generate Integrations from OpenAPI Specs

If your product, backend, or SaaS tool has an OpenAPI/Swagger spec, HiveMind can read it and help generate a Bothive integration from the available endpoints.

What is an OpenAPI spec?

An OpenAPI spec is a machine-readable map of an API. It tells Bothive:

• the API's base URL
• which endpoints exist, like GET /customers or POST /tickets
• what inputs each endpoint needs
• what auth the API expects
• what each operation is supposed to do

You can think of it as API documentation in a format software can understand. Swagger is the older/common name many tools still use for the same idea.

Where do I find one?

Try these places:

• Your API provider's developer docs. Look for OpenAPI, Swagger, API schema, or Download spec.
• A Swagger UI page. Many APIs have a docs page with a button/link for openapi.json, swagger.json, or api-docs.
• Your backend framework:
  • FastAPI often exposes /openapi.json.
  • NestJS projects often expose Swagger docs from the app's docs route.
  • Rails, Laravel, Express, Django, and Spring projects may need a plugin/package to export one.
• Ask your developer or API provider: "Can you send me the OpenAPI JSON file for this API?"

Common spec URLs look like:

text
https://api.example.com/openapi.json
https://api.example.com/swagger.json
https://api.example.com/api-docs

1. Export your spec as JSON

HiveMind currently accepts OpenAPI or Swagger JSON files. If your spec is YAML, export or convert it to JSON first.

Supported:

• .json
• OpenAPI 3.x with paths
• Swagger 2.0 with paths

Not supported yet:

• .yaml / .yml uploads
• PDFs or screenshots as API specs
• private docs pages that require login, unless you export the JSON file first

2. Upload it to HiveMind

1. Open Dashboard → HiveMind.
2. Click the + button in the composer.
3. Choose your OpenAPI/Swagger JSON file.
4. HiveMind parses the operations and starts an integration-build session.

3. Review the generated integration

HiveMind summarizes the API name, base URL, and parsed operations. Then Architect proposes a custom integration with clean bot-facing capabilities.

HiveMind turns raw API operations into bot-ready actions:

OpenAPI field	How HiveMind uses it
	Sets the base URL
	Finds available endpoints
	Suggests capability names
	Builds the input form/schema
	Defines JSON the bot must provide
	Detects bearer/API-key/OAuth auth

For example, an API operation like:

http
POST /tickets

can become a bot capability such as:

hivelang
call acme_support.createTicket with { body: ticketPayload }

4. Connect credentials

After generation, open the generated integration and connect the required credentials. Bots should only use the API after the integration is connected and tested.

5. Attach it to a bot

Once the integration is connected, ask HiveMind to build or update a bot with the new actions:

text
Update my Support Ops bot so it can:
- look up a customer by email
- create a support ticket
- update the ticket status after it replies
Use the Acme Support integration we just generated.

The bot should list the generated capabilities in its tool set instead of falling back to generic web search.

Review checklist

Before you approve the generated integration, check:

Question	Why it matters
Is the base URL production or sandbox?	Prevents bots from writing test data to prod by accident
Are write actions clearly named?	Reduces accidental misuse by agents
Are required inputs described?	Helps HiveMind collect the right fields from users
Does auth match the provider docs?	Avoids confusing runtime failures
Are sensitive actions marked for approval?	Keeps destructive work under human control

What if I do not have an OpenAPI spec?

You can still use HiveMind. Paste the API docs URL or describe the endpoints you need.

Good prompt:

text
Help me create an integration for Acme Support.
Base URL: https://api.acme.com/v1
Auth: Bearer API key
Endpoints I need:
- GET /tickets — list tickets
- POST /tickets — create a ticket
- PATCH /tickets/{id} — update status

HiveMind can then ask follow-up questions and generate the integration manually.

Tips

• Keep specs under 2MB.
• Large APIs are summarized in batches; ask HiveMind which endpoint group to prioritize.
• Use clear operation IDs in your OpenAPI file for cleaner capability names.
• If HiveMind asks a question about auth or base URL, answer it before approving the generated integration.
• Start with the endpoints your bot actually needs. A small, focused API integration is usually better than importing every endpoint.