Reference

GoBrief API

JSON REST API for partners, deliveries, collections, and partner links. The full UI runs on the same endpoints. If you can do it in the product, you can do it through the API.

Overview

Base URL: https://gobrief.co/api

All requests and responses are JSON unless noted (file uploads aremultipart/form-data). Timestamps are Unix seconds (integer) or ISO-8601 strings where documented. All responses include a Content-Type: application/json; charset=utf-8 header.

API access is currently in private beta. The endpoints below power the GoBrief product today. Formal stability guarantees kick in with the public v1 launch.

Authentication

Two authentication modes are supported:

  1. Session cookie: set by NextAuth on sign-in via Google OAuth or Resend magic link. Used by the product UI.
  2. Bearer API key: Authorization: Bearer gb_.... Generated in Settings → Integrations (or Settings → Figma for the plugin-scoped variant). Keys are scoped to one user in one workspace, and can be revoked at any time.

Cookie-authenticated requests must include a CSRF token for write operations (POST, PATCH, DELETE). The UI handles this automatically; external integrations should use Bearer keys.

Rate limits

Per-IP + per-API-key limits apply to public endpoints. Default: 30 req/min for authenticated API calls, 10 req/min for unauthenticated public tools like brand extraction. Over-limit responses return 429 Too Many Requests with a Retry-After header.

Business + Scale customers can request elevated limits by emailing hello@gobrief.co.

Errors

Errors return non-2xx HTTP status codes plus a JSON body:

{
  "error": "Workspace not found",
  "code": "not_found",
  "requiredPlan": "pro" // present only on plan-gate 402s
}

402 Payment Required returns when a request would exceed your plan's quota. The requiredPlan field tells you the minimum tier that unlocks the action.

Workspaces

GET
/api/auth/session

Return the current session (user + active org, or null).

GET
/api/collections

List collections visible to the current user in the active workspace.

POST
/api/workspaces/switch

Switch the active workspace cookie. Body: { orgId }.

PATCH
/api/org

Update workspace brand settings, voice, glossary, industry.

Partners (Contacts)

GET
/api/recipient-data

List all partner contacts in the workspace.

POST
/api/recipients

Create a new partner contact.

POST
/api/recipients/import

Bulk import from CSV.

Projects + placements

GET
/api/projects

List projects in the workspace.

POST
/api/projects

Create a project.

POST
/api/placements

Create a placement on a project.

Requests

POST
/api/requests

Create a request. Accepts `payloadKind: files | spec_request | review`.

POST
/api/requests/send

Fan out magic-link emails for a request.

POST
/api/upload

Recipient-side upload (multipart). Magic-link authenticated.

POST
/api/assignments/confirm

Reverse approval: partner confirms or rejects pending changes.

Deliveries

POST
/api/deliveries

Create a delivery. Accepts `payload_kind: files | preview | spec_sheet`.

POST
/api/deliveries/send

Send a delivery to recipients.

POST
/api/figma/intake

Receive an exported frame from the Figma plugin as a preview delivery.

Collections (Library ACL)

GET
/api/collections

List collections visible to the current user.

POST
/api/collections

Create a collection. Owners + admins only.

POST
/api/collections/[id]/assets

Add an asset to a collection.

DELETE
/api/collections/[id]/assets

Remove an asset from a collection.

Webhooks

First-class webhooks are on the roadmap. Today, the API fires outbound events through two mechanisms:

  • Stripe webhooks at /api/stripe/webhook, signed by Stripe, used for subscription lifecycle.
  • Figma intake webhook at /api/figma/intake, inbound from the plugin, authenticated by API key.

Custom outbound webhooks (request.submitted, submission.approved, delivery.downloaded, etc.) ship in v1, available on Business + Scale. Email hello@gobrief.co if you need webhook access now.

Need early API access?

Formal v1 lands with public webhooks + stability guarantees. Want to build against the beta today?

Email hello@gobrief.co