Skip to content

Instantly share code, notes, and snippets.

@nerdburn

nerdburn/api-readme.md

Last active April 23, 2026 21:35
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save nerdburn/9a22b78f09d9f36d1700542c0811b517 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save nerdburn/9a22b78f09d9f36d1700542c0811b517 to your computer and use it in GitHub Desktop.
Download ZIP
Coffee & Contracts API — Developer Guide
Raw
api-readme.md

Coffee & Contracts API — Developer Guide

Public link: https://gist.github.com/nerdburn/9a22b78f09d9f36d1700542c0811b517

Base URL: https://coffee-contracts-api-prod-5f404faa0cec.herokuapp.com

This document describes how to authenticate with the Coffee & Contracts API using API keys and what capabilities are available.

Authentication

Generating an API Key

Create an API key by calling the key management endpoint with your existing session token:

POST /api/user/api-keys
Authorization: Bearer <your-session-token>
X-Tenant-Slug: <tenant-slug>
Content-Type: application/json

{
  "name": "My Integration",
  "scope": "user"
}

Response (201):

{
  "id": "uuid",
  "name": "My Integration",
  "keyPrefix": "abcdefgh",
  "rawKey": "cc_aBcDeFgH1234567890...",
  "createdAt": "2026-04-21T00:00:00Z"
}

Important: The rawKey is only returned once at creation. Store it securely — it cannot be retrieved again.

Scopes:

  • "user" — the key authenticates as you personally.
  • "organization" — the key authenticates as the organization admin. Only org admins can create organization-scoped keys.

Using an API Key

Include the key as a Bearer token in the Authorization header, along with the X-Tenant-Slug header:

GET /api/user/content/posts-v2
Authorization: Bearer cc_aBcDeFgH1234567890...
X-Tenant-Slug: coffee-contracts

The API key grants the same permissions as logging in through the web app. All endpoints that work with a session token also work with an API key.

Managing API Keys

Action Method Endpoint
List active keys GET /api/user/api-keys
Create a key POST /api/user/api-keys
Revoke a key DELETE /api/user/api-keys/{key_id}

Revoking a key immediately invalidates it. Only the key owner (or org admin for org-scoped keys) can revoke.

API Overview

All endpoints are prefixed with /api. Requests and responses use camelCase JSON.

Pagination

List endpoints return paginated results:

{
  "results": [...],
  "count": 100
}

Use limit and offset query parameters to paginate (default page size: 25).

Available Endpoints

Content Library

Method Endpoint Description
GET /user/content/posts-v2 List all posts with favorite/used/AI-caption state. Supports filtering by content type, pillar, audience, date range, trending, and picked-for-you.
GET /user/content/posts-v2/{id_or_slug} Get a single post with full detail.
PATCH /user/content/posts-v2/{id_or_slug} Toggle favorite or used state on a post.
GET /user/content/content-types List content types (Reel, Carousel, etc.) with live post counts.
GET /user/content/content-type-categories List content type categories.
GET /user/content/content-pillars List content pillars with live post counts.
GET /user/content/content-pillar-categories List content pillar categories.
GET /user/content/content-tags List content tags with live post counts.
GET /user/content/target-audiences List target audiences with live post counts.
GET /user/content/post-photos List post photos. Filterable by comma-separated ids.
GET /user/content/post-photos/{id} Get a single post photo.
GET /user/content/styles List content styles. Filterable by date (year/month).
GET /user/content/content-drops List content drops grouped by week. Filterable by month.
GET /user/content/content-drops/{week_of} Get all posts in a specific weekly drop.
GET /user/content/trending-reels List trending reel/dashboard posts.
GET /user/content/picked-for-you Get pillars and tags matched to your onboarding preferences.
GET /user/content/item-filters Get counts of posts, images, and videos matching the current filter.
GET /user/content/items List all content items (posts + images) with favorite/used state.
PATCH /user/content/items/{item_id} Mark an item as favorite/unfavorite or used/unused.

Content Calendar & Schedule

Method Endpoint Description
GET /user/content/schedule List your content schedule. Supports date, date range, month, and recommended filters.
POST /user/content/schedule Add a post to your schedule at a specific date and order.
PATCH /user/content/schedule/{id} Update a schedule entry (mark completed or swap the post).
DELETE /user/content/schedule/{id} Remove a post from the schedule.
DELETE /user/content/schedule Reset a date back to its default schedule.
POST /user/content/reorder-schedule Reorder/move posts between dates via drag-and-drop.
POST /user/content/generate-calendar Generate a content calendar for a given month and days-of-week.
GET /user/content/calendar-categories List calendar categories.
GET /user/content/daily-tasks List daily tasks. Filterable by is_completed and date.
PATCH /user/content/daily-tasks/{task_id} Mark a daily task as completed or not.

AI Assistant

Method Endpoint Description
GET /user/my-market-profile Get your AI market profile (status, voice tags, summary).
POST /user/my-market-profile Trigger AI generation of your market profile.
GET /user/ai-assistant/market-profile-categories List market profile questions with your answers.
POST /user/ai-assistant/market-profile-answers Save answers to market profile questions.
GET /user/ai-assistant/ai-generation-tasks List AI generation tasks. Filterable by status and type.
POST /user/ai-assistant/ai-generation-tasks Create a reel script generation task from a selected hook.
GET /user/ai-assistant/ai-generation-tasks/{id} Get status of a generation task.
GET /user/ai-assistant/ai-generation-tasks/hook-menu Get the current reel hook menu.
POST /user/ai-assistant/ai-generation-tasks/hook-menu Generate a new reel hook menu.
GET /user/ai-assistant/ai-generation-tasks/hook-menu/status Get hook menu generation status.
GET /user/ai-assistant/user-reel-scripts/{id_or_slug} Get a completed reel script.
GET /user/ai-assistant/feature-model-settings Get AI feature metadata (which features are enabled).

AI Captions

Method Endpoint Description
POST /user/content/ai-caption Generate or regenerate an AI caption for a post.
POST /user/content/ai-caption-reaction Save a thumbs-up/down reaction to an AI caption.

Events

Method Endpoint Description
GET /user/event/events List live events with your attendee status. Filterable by category, type, tags, upcoming/past.
GET /user/event/events/{id_or_slug} Get a single event.
GET /user/event/event-types List event types with live events.
POST /user/event/register Register or unregister for an event.

Resources (Stock Images & Knowledge Hub)

Method Endpoint Description
GET /user/resources/images List stock images/videos with favorite/used state. Filterable by shoot, tags, type, orientation.
GET /user/resources/image-filters Get image filter metadata (counts by orientation, type, shoot, tag).
GET /user/resources/knowledge-hub-videos List knowledge hub videos. Filterable by category and title search.
GET /user/resources/knowledge-hub-video-categories List video categories with counts.

Page Builder

Method Endpoint Description
GET /user/pagebuilder/pages List your pages.
GET /user/pagebuilder/pages/{id_or_slug} Get a page with all components, images, and social links.
POST /user/pagebuilder/pages Create a new page with default components.
PATCH /user/pagebuilder/pages/{id_or_slug} Update page metadata (title, slug, style, status).
DELETE /user/pagebuilder/pages/{id_or_slug} Delete a page.
POST /user/pagebuilder/duplicate-page Duplicate a page (deep copy).
POST /user/pagebuilder/page-components Add a component to a page.
PATCH /user/pagebuilder/page-components/{id} Update a component.
DELETE /user/pagebuilder/page-components/{id} Delete a component.
POST /user/pagebuilder/component_images Attach an image to a component.
DELETE /user/pagebuilder/component_images/{id} Remove an image from a component.
POST /user/pagebuilder/social-links Add a social link.
PATCH /user/pagebuilder/social-links/{id} Update a social link.
DELETE /user/pagebuilder/social-links/{id} Delete a social link.

Account & Profile

Method Endpoint Description
GET /user/my-profile Get your full profile.
PATCH /user/my-profile Update profile fields (name, email, location, preferences, onboarding traits, etc.).
POST /user/change-password Change your password.
GET /user/my-activity Get your activity summary (items used, favorited, events attended).
GET /user/my-tour-progress Get onboarding tour progress.
PATCH /user/my-tour-progress Update tour progress.

Organization

Method Endpoint Description
GET /user/my-organization Get your organization with member list.
POST /user/my-organization Create or rename your organization.
DELETE /user/my-organization Leave your organization (non-admins only).

Billing & Subscription

Method Endpoint Description
GET /user/my-membership Get your current membership and billing info.
GET /user/my-coupon Get details of your currently applied coupon.
GET /user/payment/memberships List available membership plans.
GET /user/payment/invoices List your invoices.
GET /user/payment/invoice-url/{id} Get the receipt URL for an invoice.
POST /user/payment/send-invoice-csv Email an invoice CSV export to yourself.
POST /user/payment/checkout Start a subscription checkout (returns Stripe client secret).
POST /user/payment/apply-coupon Apply a coupon to your account.
POST /user/payment/remove-coupon Remove the applied coupon.
POST /user/payment/cancel-membership Cancel your subscription.
POST /user/payment/reactivate-plan Reactivate a cancelled subscription.
POST /user/payment/change-plan Switch to a different plan.
POST /user/payment/pause-membership Pause your subscription.
POST /user/payment/unpause-membership Unpause your subscription.
POST /user/payment/refresh-billing Sync billing info with Stripe.
POST /user/payment/update-billing Update your payment method (returns Stripe client secret).

Instagram Analytics

Method Endpoint Description
GET /user/my-ig-info Get your Instagram profile info.
DELETE /user/my-ig-info Disconnect Instagram.
GET /user/my-ig-insights Get Instagram user-level insights.
GET /user/my-ig-media List your Instagram media.
GET /user/instagram/media-insights/{media_id} Get insights for a specific post.
GET /user/instagram/posting-frequency Get your average posts per week.
GET /user/instagram/summary Get aggregated Instagram analytics summary.
DELETE /user/instagram/summary Disconnect Instagram and delete cached data.

Search

Method Endpoint Description
GET /user/content/search Full-text search across posts and events.
GET /user/content/search-filters Get filter options for a search query.

Files

Method Endpoint Description
POST /user/files/create-signed-file Get a pre-signed S3 upload URL.

Feature Flags

Method Endpoint Description
GET /public/feature-flags List feature flags with enabled status (works with or without auth).

Notifications

Method Endpoint Description
GET /user/content/notifications List platform notifications with read status.

Onboarding Traits

Method Endpoint Description
GET /user/content/areas-of-work List areas of work.
POST /user/content/areas-of-work Create a custom area of work.
GET /user/content/client-types List client types.
POST /user/content/client-types Create a custom client type.
GET /user/content/mindset List content mindsets.
POST /user/content/mindset Create a custom content mindset.
GET /user/content/user-goals List user goals.
POST /user/content/user-goals Create a custom user goal.
GET /user/content/referral-sources List referral sources.
POST /user/content/referral-sources Create a custom referral source.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment