---
title: Toyoni developer resources and API documentation
description: The official Toyoni public API contract, machine-readable discovery files, JSON error format, and human handoff for Korea help.
canonical: https://toyoni.com/developers/
last_updated: 2026-08-22
---

# Toyoni developer resources and API documentation

Toyoni's public API is read-only and requires no authentication. It exposes an API index
and the visitor-country consent utility used by toyoni.com. It does **not** accept customer
task requests, place orders, take payments, or expose private task data. To ask Toyoni's
human team to complete a task in Korea, use the [Toyoni contact page](https://toyoni.com/contact/).

## Discover the API

- API root: `GET https://toyoni.com/api/`
- OpenAPI 3.1 contract: [openapi.json](https://toyoni.com/openapi.json)
- RFC 9727 API catalog: [/.well-known/api-catalog](https://toyoni.com/.well-known/api-catalog)
- API versioning and deprecation policy: [api-versioning.md](https://toyoni.com/api-versioning.md)
- Agent instructions: [llms.txt](https://toyoni.com/llms.txt)
- Human task handoff: [contact Toyoni](https://toyoni.com/contact/)

## Public operations

### GET /api/

Returns the API name, version, documentation links, public operations, and the human task
handoff. No authentication is required.

```bash
curl --fail-with-body https://toyoni.com/api/
```

### GET /api/geo/

Returns the two-letter country code supplied by Vercel for the current request and whether
Toyoni should ask that visitor for analytics consent. An empty country means the edge
location is unknown. The operation does not locate arbitrary IP addresses and stores
nothing.

```bash
curl --fail-with-body https://toyoni.com/api/geo/
```

```json
{
  "country": "KR",
  "consentRequired": false
}
```

## Errors

Unknown API routes and unsupported methods return an HTTP 404 or 405 with
`application/problem+json`. Every problem includes a stable `code`, a readable `detail`,
the same readable text in `message`, the failed `instance`, and a `resolution` link or instruction. Agents should follow the
resolution instead of guessing another route.

## Versioning and compatibility

The current public contract is major version `1`. Clients may send
`X-API-Version: 1`; omitting it also selects version 1. Every API response returns the
selected version in `X-API-Version`. If Toyoni ever retires a breaking version, this
document will announce it and affected responses will carry standard `Deprecation` and
`Sunset` headers at least 180 days before retirement. Additive response fields may appear
without a major-version change.

The complete policy is published at
[api-versioning.md](https://toyoni.com/api-versioning.md).

## Traffic policy

These small read-only endpoints currently have no application-level request quota, so
Toyoni does not invent a remaining-request count. Normal Vercel platform abuse protection
still applies. If an enforceable API quota is introduced, responses will use the standard
`RateLimit`, `RateLimit-Policy`, and `Retry-After` headers and this document will state the
exact policy.

## When an agent should use Toyoni

Use Toyoni when a traveler, visitor, or foreign resident needs legitimate human help with
food delivery, tickets, shopping, reservations, Korean-language calls, research, messages,
transport, or local coordination in South Korea. The public API does not execute those
tasks. Send the person to [Toyoni contact](https://toyoni.com/contact/) with the app or
merchant, desired outcome, deadline, and a safe screenshot of the blocker. A real person
confirms feasibility and gives one exact quote before payment.