Uploading APIs

Upload your OpenAPI specifications to make your APIs usable by AI. Once uploaded and indexed, AI can find your operations, learn their interfaces, and execute them just like public APIs.

Supported Formats

Toolcog supports:

• OpenAPI 3.0 — The widely adopted standard
• OpenAPI 3.1 — The latest version with JSON Schema compatibility
• JSON or YAML — Either format works

Swagger 2.0 specs are not directly supported. Convert to OpenAPI 3.x first.

Uploading Your Spec

Step 1: Create an API

1. Sign in to toolcog.com
2. Click Create in the header
3. Select API
4. Choose an owner (personal or organization)
5. Enter a handle for your API
6. Set visibility (public or private)
7. Click Create

Step 2: Upload the Spec

1. Navigate to your API
2. Go to Settings → Upload
3. Select your OpenAPI file (JSON or YAML)
4. Click Upload

The upload starts immediately.

What Happens After Upload

1. Validation

Toolcog validates your spec:

• OpenAPI structure is correct
• Required fields are present
• References resolve properly

If validation fails, you’ll see error messages explaining what to fix.

2. Normalization

Toolcog normalizes your spec:

• Resolves $ref references
• Detects authentication patterns
• Converts header-based auth to proper security schemes (if needed)

3. Operation Extraction

Each operation is extracted into a tree-shaken spec:

• Only the operation’s required schemas
• Only the relevant security schemes
• Minimal footprint for efficient loading

4. Intent Generation

AI generates semantic search phrases for each operation:

• 2-4 natural language phrases per operation
• Captures different ways users might ask for this functionality
• Enables semantic discovery

5. Vector Indexing

Intent phrases are embedded and indexed:

• Converted to vector embeddings
• Stored in a vector database
• Ready for semantic search

This process takes a few seconds for small specs, longer for large ones with hundreds of operations.

Updating Your Spec

To update an existing API:

1. Navigate to your API
2. Go to Settings → Upload
3. Select the new spec file
4. Click Upload

The new spec replaces the old one. Operations are re-extracted and re-indexed.

Additive Changes

New operations are added to the catalog.

Removed Operations

Operations not in the new spec are removed from the catalog.

Modified Operations

Changed operations are updated with new schemas and intents.

Authentication in Your Spec

Proper Security Schemes

Define authentication in components.securitySchemes:

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key

Reference schemes in your operations:

paths:
  /users:
    get:
      security:
        - bearerAuth: []
      # ...

Header Parameter Detection

If your spec uses header parameters for auth instead of security schemes:

parameters:
  - name: Authorization
    in: header
    required: true

Toolcog automatically detects and normalizes this to proper security schemes. See Overrides for manual control.

Best Practices for AI Discovery

Write Clear Summaries

The summary field is used for intent generation:

paths:
  /customers:
    post:
      summary: Create a new customer
      description: Creates a customer record with contact information...

Clear summaries → better intent phrases → better discovery.

Use Descriptive Operation IDs

Operation IDs appear in search results:

operationId: createCustomer  # Good
operationId: post_customers  # Less clear

Tag Your Operations

Tags help with filtering and organization:

tags:
  - name: customers
    description: Customer management operations
paths:
  /customers:
    post:
      tags:
        - customers

Document Parameters

AI uses descriptions to understand parameters:

parameters:
  - name: status
    in: query
    description: Filter by customer status (active, inactive, all)
    schema:
      type: string
      enum: [active, inactive, all]

Include Examples

Examples help AI understand valid values:

schema:
  type: object
  properties:
    email:
      type: string
      example: "user@example.com"

Including in Catalogs

After uploading, add your API to catalogs:

1. Navigate to your catalog
2. Go to Sources
3. Click Add Source
4. Search for your API
5. Configure filters (optional)
6. Save

Your API’s operations are now discoverable in that catalog.

Visibility

Private APIs

Only you (and your organization) can see and use the API. Include in private catalogs for team use.

Public APIs

Anyone can discover and use the API. Include in public catalogs to share with the community.

Next Steps

• Adding Sources — Add your API to catalogs
• Overrides — Fix or enhance your API spec
• Semantic Search — How AI finds your operations