Skip to content
Farcaster

Overview

Farcaster Gateway API 1.0.0

Section titled “Farcaster Gateway API 1.0.0”

The Farcaster gateway’s /v1 REST surface: the Agent Catalog, credential vault, transactional/streaming proxy, invocation and analytics observability, settlement configuration, and per-tenant policy authoring. This document describes existing, implemented behavior — it is generated by hand from gateway/internal/httpapi/ and is the canonical contract the product website’s API reference renders from (spec 0008, Resolved Decision 3). Any change to a handler’s request/response shape must update this file in the same PR (spec 0008 T7 wires a CI drift-guard over this pairing). Two operational routes (/healthz, /version) sit outside /v1 and require no authentication (AGENTS.md invariant #1).

docs/specs/ (product specs 0001-0006 this surface implements)

Information

  • OpenAPI version: 3.0.3

Operations

Section titled “Operations”
GET
/healthz
GET
/version
GET
/v1/agents
POST
/v1/agents
GET
/v1/agents/{id}
DELETE
/v1/agents/{id}
PATCH
/v1/agents/{id}
GET
/v1/credentials
POST
/v1/credentials
GET
/v1/credentials/{id}
PUT
/v1/credentials/{id}
DELETE
/v1/credentials/{id}
POST
/v1/proxy/{id}
POST
/v1/proxy/{id}/stream
GET
/v1/proxy/{id}/invocations/{inv_id}
GET
/v1/invocations
GET
/v1/invocations/{id}
GET
/v1/analytics
GET
/v1/settlement/config
PATCH
/v1/settlement/config
GET
/v1/policy
PUT
/v1/policy
GET
/v1/policy/decisions

Authentication

Section titled “Authentication”

oidcBearer

Section titled “oidcBearer”

An OIDC-issued bearer JWT, validated against the gateway’s configured issuer/audience (FARCASTER_OIDC_ISSUER/FARCASTER_OIDC_AUDIENCE). The token’s tenant and user claims (configurable claim names) become the caller’s identity; every /v1 route requires both to be present. Missing or invalid tokens return 401 with no body. Some routes also check a scope claim (e.g. invocations:read_body on GET /v1/invocations/{id}). /healthz and /version are exempt.

Security scheme type: http

Bearer format: JWT