Discovering APIs for AI Agents: A Practical Koyori Utils API Example

AI agents are increasingly useful when they can discover tools, inspect their capabilities, and decide which API to use.

But a good agent workflow should separate API discovery from purchasing and executing paid operations.

Here's a practical example using Koyori Utils API, a service offering 20,000 API operations for developers, bots, and AI agents.

Step 1: Find available tools

Koyori Utils API provides a public discovery catalog.

You can explore it here:

https://koyori-utils-api.koyori-aibtc.workers.dev/agents/catalog

For example, search for JSON-related tools:

curl -G \
  "https://koyori-utils-api.koyori-aibtc.workers.dev/agents/catalog" \
  --data-urlencode "q=json" \
  --data-urlencode "limit=3"

Inspect the returned catalog data to find an operation relevant to your task.

Step 2: Inspect the OpenAPI specification

Before calling an endpoint, inspect its supported method, request schema, and response format.

OpenAPI specification:

https://koyori-utils-api.koyori-aibtc.workers.dev/openapi.json

This helps prevent AI agents from guessing endpoint names or sending malformed requests.

Step 3: Try a read-only Python example

This example retrieves a small catalog search without purchasing anything or executing a paid utility operation.

import json
from urllib.parse import urlencode
from urllib.request import urlopen

base = "https://koyori-utils-api.koyori-aibtc.workers.dev"
query = urlencode({"q": "json", "limit": 3})

with urlopen(f"{base}/agents/catalog?{query}", timeout=20) as response:
    catalog = json.load(response)

print(json.dumps(catalog, indent=2)[:3000])

This is a discovery example, not a payment or subscription automation.

Step 4: Understand payments before using paid APIs

Koyori Utils API includes STX subscription options.

Check the live subscription page for current plans and purchasing instructions:

https://koyori-utils-api.koyori-aibtc.workers.dev/subscription

An autonomous agent should always obtain explicit human authorization before making a purchase or signing a wallet transaction.

If a payment is pending, it should not automatically retry and risk paying twice.

Step 5: Follow the AI agent quickstart

The AI-oriented guide explains the discovery, purchasing, and activation workflow:

https://koyori-utils-api.koyori-aibtc.workers.dev/agents/quickstart

A fuller GitHub discovery example is available here:

https://github.com/sophiaalice0913-cmyk/koyori-utils-api/blob/main/docs/AI_AGENT_DISCOVERY_EXAMPLE.md

Final thoughts

A useful AI agent integration should be:

• Discoverable: tools and schemas are accessible.
• Predictable: operations are inspected before use.
• Secure: secrets and API keys remain private.
• Payment-safe: purchases require authorization, with no automatic duplicate payments.

If you're building API-powered AI agents, feel free to explore the catalog and documentation.

Project: https://koyori-utils-api.koyori-aibtc.workers.dev/

Disclosure: This article introduces a project I am involved with. It was prepared with AI writing assistance.