API Overview

The Guppy API is organized around REST. All API responses are returned in JSON format.

Base URL

https://api.guppy.ai/v1

Content Type

Send JSON request bodies with:

Content-Type: application/json

Authentication

All requests must include:

Authorization: Bearer GUPPY_SECRET_KEY

Idempotency (Recommended for Writes)

All write operations accept:

Idempotency-Key: <string>

If the same key is reused, Guppy will return the same result as the first successful request (see idempotency).

Request IDs

Every API response includes a request_id field (and may also include an X-Request-Id header). If you contact support, include this ID so we can trace the execution.

Pagination

List endpoints are cursor-based:

limit: number of items to return (default and max may vary by partner)
starting_after: return results after this ID

Example:

GET /intents?external_user_id=user_123&limit=25&starting_after=int_100

Key Resources

Intents: Create and manage commerce goals.
Events: Subscribe to state changes and execution updates.
Payments: Manage funding sources and spend authority.
Receipts: Access cryptographic proof of execution.

​Base URL

​Content Type

​Authentication

​Idempotency (Recommended for Writes)

​Request IDs

​Pagination

​Key Resources