Connect an AI agent to a custom API using an OpenAPI spec

Your team has an inventory API. An assistant needs to look up stock for a product, but there is no ready-made connector for your service. If the API already speaks HTTP, you can describe its endpoints with OpenAPI and connect it to Loggie for use through the CLI.

You need a reachable API, its authentication details, and an accurate description of the operations you want the agent to use. The OpenAPI document supplies the contract. Loggie stores the connection configuration and applies the agent's access policy when it makes requests.

This approach does not require you to build an MCP server for the CLI workflow. It also does not implement the underlying API, expose a private network, or make every authentication protocol compatible automatically.

Start with one useful endpoint

Suppose your API has a read operation:

GET /inventory/{sku}
Authorization: Bearer YOUR_PROVIDER_TOKEN

It returns a SKU, an available quantity, and the time the inventory was updated. That is enough for an assistant to answer "How much stock is available for this product, and how fresh is that number?"

The API and data in this guide are illustrative. inventory.example.com is a placeholder, not a working demo service. Adapt the contract to an endpoint you already operate, and use a staging API with synthetic data for your first test.

Avoid importing a large API surface just to answer one question. Begin with the endpoint whose response you can inspect and whose authorization you understand. You can add operations after that read works.

Describe the contract in OpenAPI

Save the following as inventory.openapi.yaml, replacing the server URL and schema with your API's real contract:

openapi: 3.0.3
info:
  title: Inventory lookup API
  version: 1.0.0
servers:
  - url: https://inventory.example.com/v1
security:
  - providerToken: []
paths:
  /inventory/{sku}:
    get:
      operationId: getInventoryBySku
      summary: Read available stock for a product SKU
      description: Returns current stock without changing inventory.
      parameters:
        - name: sku
          in: path
          required: true
          schema:
            type: string
          example: DEMO-001
      responses:
        '200':
          description: Inventory for the requested SKU
          content:
            application/json:
              schema:
                type: object
                required:
                  - sku
                  - available
                  - updatedAt
                properties:
                  sku:
                    type: string
                  available:
                    type: integer
                    minimum: 0
                  updatedAt:
                    type: string
                    format: date-time
        '401':
          description: Missing or invalid provider credentials
        '404':
          description: SKU not found
components:
  securitySchemes:
    providerToken:
      type: http
      scheme: bearer

This is an OpenAPI 3.0.3 document. The path parameter is required, response fields have types, and the authentication scheme is declared without embedding a secret.

Write descriptions that help an agent form the right request. If an inventory number excludes reserved units, say so. If the endpoint can return negative values, remove the example's minimum: 0 rather than publishing a schema that contradicts the service. A precise contract is more useful than a long description filled with general API advice.

Create the connection and configure authentication

In Loggie, use the custom or manual integration flow. Enter a connection name and the runtime base URL. In the OpenAPI specifications section, supply a spec URL, upload the file, or paste the JSON or YAML.

For this example's bearer-token API, choose header injection and add an Authorization header whose value is Bearer followed by the actual provider token. Enter that value in the connection's secret configuration, not in the specification or agent instructions.

The securitySchemes entry describes the expected authentication. It does not supply the credential. Similarly, a servers entry documents a URL; you must still check that the configured runtime base URL points to the intended environment.

Pay attention to path prefixes. If the runtime base URL includes /v1, the endpoint in this example is /inventory/{sku}. Verify the discovered path and resulting request rather than accidentally duplicating the prefix as /v1/v1/inventory/....

The service must be reachable from Loggie. A hostname that resolves only on your laptop, or an API listening only on localhost, will not become reachable by importing its spec. Arrange suitable network access separately without exposing an unauthenticated internal service to the public internet.

Give an agent access to the lookup

Create a dedicated identity, such as inventory-reader, and assign the new connection with read access. Allow the lookup endpoint and keep unknown endpoints denied. Review the imported operation's classification before making calls.

An endpoint restriction on /inventory/{sku} permits matching SKU lookups; it does not distinguish which customer owns each SKU. Keep tenant and resource authorization in the underlying API, using a provider credential scoped to the intended data. See the team permissions guide for the distinction between endpoint access and data access.

Install and initialize the CLI in the agent's execution environment:

npm install -g @loggie-ai/cli
loggie init
loggie discover

The CLI requires Node.js 20 or newer. Supply the new identity's Loggie key during initialization. The agent does not need the inventory service's bearer token.

Assuming discovery shows the connection slug inventory, inspect the operation and call it with a known staging SKU:

loggie discover inventory --method GET --search inventory --limit 10
loggie discover inventory --endpoint '/inventory/{sku}' --method GET
loggie call inventory GET /inventory/DEMO-001

Substitute your actual connection slug, discovered path, and test SKU. A response matching the example contract could look like this:

{
  "sku": "DEMO-001",
  "available": 42,
  "updatedAt": "2026-09-07T14:30:00Z"
}

That is synthetic data showing the expected shape. Check your actual result against the service's own records before letting the assistant answer inventory questions.

Fix the contract before expanding permissions

If discovery cannot find the endpoint, check whether the spec loaded and whether its paths describe the deployed API. An inaccessible spec URL, unresolved schema reference, or missing operation needs a documentation fix rather than broader agent access.

For a provider authentication error, check the configured header and token scope. For a 404, check the base URL, path prefix, and SKU. For a Loggie denial, check the identity's connection assignment, endpoint restriction, and classification. These failures happen at different stages and need different fixes.

Loggie also supports Postman collection discovery and manual configuration when a ready-made OpenAPI document is unavailable. Review the discovered operations before granting access. A collection with a few successful examples may still omit response fields or error behavior the assistant needs to understand.

Once reads work, add only the additional operations the workflow needs. An inventory-adjustment endpoint deserves a separate policy review and a staging test. If a human must approve adjustments, configure approval before the saved request is executed rather than relying on an instruction to ask first.