Core Concepts

A deeper look at the terms introduced in Quick Start.

1. API

A communication protocol for exchanging data between programs.

In 3Min API:

• Create APIs without backend code
• Receive standard JSON data
• Data is automatically stored and can be forwarded via webhooks

2. Endpoint

The API address that receives data. One API = one endpoint.

Each endpoint includes:

• Unique URL path (auto-generated)
• Required fields (optional)
• Sandbox/Production environment separation
• Environment-specific API keys (tm_test_xxx..., tm_live_xxx...)

3. JSON

3Min API accepts standard JSON data.

Supported field types:

Example (order info):

{
  "order_id": "ORD-2024-001",
  "amount": 45000,
  "items": ["Item A", "Item B"],
  "paid": true,
  "customer": {
    "name": "John Doe",
    "phone": "010-1234-5678"
  }
}

4. Required Fields (Optional)

You can specify fields that must be included in JSON data.

With required fields:

• Requests missing required fields are rejected (400 error)
• Ensure data quality

5. Sandbox vs Production

• Environment is determined by API key prefix
• Webhooks can be configured separately per environment
• Test thoroughly in Sandbox before deploying to Production

6. API Key

Used for authentication when calling endpoints. The owner's default API key is automatically generated when the endpoint is created and cannot be deleted. If the key is compromised, it can be regenerated.

Collaboration Keys

Create collaboration keys and invite collaborators to manage logs and statistics separately per collaboration key.

Filter logs by collaboration key to track usage per collaboration key.

Set allowed operations (POST/GET/PUT/DELETE) per collaboration key, independently for each environment. Read permission covers single GET, GET (list), and GET (search) alike.

7. Webhooks

Automatic notifications sent to a specified URL when data arrives.

Two types of webhooks:

Retry policy: return 2xx within 15s. On failure, delivery is retried from a queue over hours

Note: Even if all webhook retries fail, your data is still stored safely. Check webhook status in the logs.

8. Polling

The other way to receive data. Instead of us calling your URL, your client calls the polling endpoint on a loop and gets back only what arrived since its last call.

Webhook or polling:

Pick webhook when the receiver has a public URL and should react as soon as data arrives. This is the default.

Pick polling when there is no public URL — local development, an internal network, behind a firewall, no always-on server — or when the receiver needs to control its own pace.

They are not exclusive. Both can be on for the same endpoint: a webhook for real-time reaction, plus a nightly poll that backfills anything the receiver missed.

Example request:

# First call - since a point in time
GET /api/v1/data/my-endpoint/poll?since=2026-09-01
Authorization: Bearer tm_test_xxx

# Response - oldest first
{
  "success": true,
  "data": [ ... ],
  "pagination": {
    "limit": 100,
    "poll_cursor": "eyJ0IjoiMjAyNi0wOS0wMVQwMDowMDowMFoifQ"
  }
}

# Next call - send the cursor back
GET /api/v1/data/my-endpoint/poll?cursor=eyJ0IjoiMjAyNi0wOS0wMVQwMDowMDowMFoifQ

How the cursor works:

• The first call takes since (RFC 3339 or YYYY-MM-DD, always read as UTC), or nothing at all, which subscribes from that moment on. since and cursor cannot be sent together.
• next_cursor means a backlog remains — call again right away
• poll_cursor means you are caught up — save it and wait for your next cycle
• Records come oldest first, up to 100 per page (limit, 1-100). Every response carries exactly one of the two cursors

9. Tasks

Tasks let an AI such as ChatGPT or Claude hand a job to your own HTTP server — a worker — and bring the result back into the conversation. 3Min API only delivers the task and records its status; the worker does the actual work.

How a task runs:

1. The AI calls task_create with a worker name and input. The task starts as working
2. 3Min API sends a signed POST to the worker URL, including a callback_url
3. The worker answers 2xx right away — that means "received", not a result — and then does the work
4. When done, the worker reports completed or failed to the callback_url. Progress messages before that are optional
5. The AI calls task_get and shows the result in the conversation

Webhook or task:

Good to know:

• A public worker needs a public URL. Code on your own PC runs as a local worker through the 3Min API CLI instead — no public URL needed
• A task that is not finished within 24 hours becomes failed
• Delivery is at-least-once, so the same task can arrive twice — deduplicate on the task ID
• Registering a worker and viewing or rotating its secrets happen in the web dashboard only. The AI never sees the URL or secrets

Worker contract, signature verification and example code: Tasks guide

10. Data Retention

Records are kept for a limited time, so treat the webhook or the polling endpoint — not the dashboard — as the way your data leaves 3Min API.

Policy by environment:

Getting your data out:

• Webhook: every record is pushed to your URL as it arrives
• Polling: pull whatever arrived since your last call — see section 8 above
• Logs: look up or search individual records in the dashboard while they are retained
• Usage statistics are kept separately and survive record deletion, so your dashboard charts stay intact