Forge API · v1 · beta

API reference

Generate brands, names and images programmatically with the same engine that powers Forge. REST + JSON, per-action pricing, billed from a credit pool that's separate from your in-app credits.

Base URL https://ovmmedia.com/api/v1

Quickstart

Create a key in the dashboard (you get 300 free credits).
Export it: export FORGE_API_KEY=fk_live_…
Make your first call:

curl https://ovmmedia.com/api/v1/brand/names \
  -H "Authorization: Bearer $FORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idea":"coconut-wax candles","mood":"minimal"}'

Authentication

Every request must send your secret key as a bearer token. Keys look like fk_live_… and are shown once at creation, only a hash is stored, so keep them safe and server-side. Requests without a valid key get 401.

Authorization: Bearer fk_live_…

Rotate or revoke a key any time in the dashboard; revoked keys are rejected immediately. Never ship a key in client-side code.

Credits & billing

Each action costs a fixed number of API credits (1 credit = $0.01), debited from your API pool, which is completely separate from your in-app Forge credits. A failed request is automatically refunded.

Dev

2,000 credits

$20

Team

10,000 credits

$90

Scale

50,000 credits

$400

Rate limits

60 requests per minute per key. Every response carriesX-RateLimit-Limit andX-RateLimit-Remaining; a 429 includesRetry-After (seconds).

Errors

Errors return a consistent JSON envelope with a stable code and a requestId for support.

{ "error": { "code": "insufficient_credits", "message": "...", "requestId": "req_..." } }

Status	Code	When
401	missing_api_key / invalid_api_key / revoked_api_key	No, malformed, unknown, or revoked key.
402	insufficient_credits	Not enough API credits for the action.
429	rate_limited	Over 60 requests/minute. A Retry-After header is included.
500	internal_error	Something failed our side. Credits are auto-refunded.

Endpoints

All paths are relative to https://ovmmedia.com/api/v1.

POST

/brand/namesLIVE5 credits

Suggest distinctive, ownable brand names from a short product brief.

Field	Type	Notes
idea *	string	What you're selling, in a few words.
productType	string	Category hint, e.g. 'candles'.
audience	string	Who it's for.
mood	string	Brand mood, e.g. 'minimal'.

Request

curl https://ovmmedia.com/api/v1/brand/names \
  -H "Authorization: Bearer $FORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idea":"coconut-wax candles","mood":"minimal"}'

Response

{
  "data": {
    "names": [
      "Lumen",
      "Wickwood",
      "Coco & Ember",
      "Hearthe",
      "Slowburn",
      "Wax + Wander"
    ],
    "stub": false
  },
  "usage": {
    "credits": 5,
    "balance": 1880,
    "requestId": "req_…"
  }
}

POST

/brand/buildLIVE120 credits

Run the full multi-agent brand + store generation and return every module.

Field	Type	Notes
intake *	object	Intake answers. `idea` is required; the rest is optional and improves the result.

Request

curl https://ovmmedia.com/api/v1/brand/build \
  -H "Authorization: Bearer $FORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"intake":{"idea":"coconut-wax candles for cozy apartments","productType":"candles","audience":"design-led renters","mood":"minimal","brandName":"Lumen"}}'

Response

{
  "data": {
    "workspaceId": "ws_3f9c…",
    "generatedModules": [
      "brand_identity",
      "market",
      "financial_plan",
      "product_strategy",
      "store_blueprint"
    ],
    "modules": {
      "brand_identity": {
        "recommended_name": "Lumen",
        "positioning": "…",
        "palette": [
          "…"
        ]
      },
      "store_blueprint": {
        "hero": {
          "headline": "…"
        }
      }
    }
  },
  "usage": {
    "credits": 120,
    "balance": 1880,
    "requestId": "req_…"
  }
}

POST

/images/generateLIVE4 credits / image

Generate one or more on-brand images. Charged per image.

Field	Type	Notes
images *	array	Up to 8 requests, each `{ label, prompt, kind?, palette? }`. `kind` ∈ logo\|moodboard\|palette\|packaging\|product.

Request

curl https://ovmmedia.com/api/v1/images/generate \
  -H "Authorization: Bearer $FORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"images":[{"label":"Hero","kind":"product","prompt":"a single lit coconut-wax candle on linen, soft morning light","palette":["#0F172A","#F97316"]}]}'

Response

{
  "data": {
    "images": [
      {
        "label": "Hero",
        "kind": "product",
        "url": "https://cdn.ovmmedia.com/…png",
        "stub": false
      }
    ],
    "stub": false
  },
  "usage": {
    "credits": 4,
    "balance": 1880,
    "requestId": "req_…"
  }
}

GET

/usageLIVEfree

Your current API credit balance and recent usage. Free.

Request

curl https://ovmmedia.com/api/v1/usage \
  -H "Authorization: Bearer $FORGE_API_KEY"

Response

{
  "data": {
    "balance": 1880,
    "recent": [
      {
        "endpoint": "brand.build",
        "credits": 120,
        "status": 200,
        "created_at": "2026-06-15T…"
      }
    ]
  },
  "usage": {
    "credits": 0,
    "balance": 1880,
    "requestId": "req_…"
  }
}

POST

/brand/boardSOON24 credits

Generate the brand visual board (mood, product, packaging, lifestyle).

Request

curl https://ovmmedia.com/api/v1/brand/board \
  -H "Authorization: Bearer $FORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workspaceId":"ws_3f9c…"}'

Response

{
  "data": {
    "tiles": [
      {
        "label": "Mood",
        "url": "…"
      }
    ]
  },
  "usage": {
    "credits": 24,
    "balance": 1880,
    "requestId": "req_…"
  }
}

POST

/brand/logoSOON6 credits

Generate a logo concept (plain + applied to packaging).

Request

curl https://ovmmedia.com/api/v1/brand/logo \
  -H "Authorization: Bearer $FORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workspaceId":"ws_3f9c…","instruction":"more minimal"}'

Response

{
  "data": {
    "url": "…",
    "applied_url": "…"
  },
  "usage": {
    "credits": 6,
    "balance": 1880,
    "requestId": "req_…"
  }
}

POST

/site/generateSOON20 credits

Compose a multi-page storefront from a brand.

Request

curl https://ovmmedia.com/api/v1/site/generate \
  -H "Authorization: Bearer $FORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workspaceId":"ws_3f9c…"}'

Response

{
  "data": {
    "siteId": "site_…",
    "pages": 4
  },
  "usage": {
    "credits": 20,
    "balance": 1880,
    "requestId": "req_…"
  }
}

POST

/site/edit-blockSOON3 credits

Edit one storefront block with a plain-language instruction.

Request

curl https://ovmmedia.com/api/v1/site/edit-block \
  -H "Authorization: Bearer $FORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workspaceId":"ws_3f9c…","blockType":"hero","instruction":"punchier headline"}'

Response

{
  "data": {
    "props": {
      "headline": "…"
    }
  },
  "usage": {
    "credits": 3,
    "balance": 1880,
    "requestId": "req_…"
  }
}

POST

/video/generateSOON400 credits / scene

Generate a UGC/explainer video. Async, charged per 8s scene.

Request

curl https://ovmmedia.com/api/v1/video/generate \
  -H "Authorization: Bearer $FORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workspaceId":"ws_3f9c…","duration":8,"mode":"ugc"}'

Response

{
  "data": {
    "assetIds": [
      "asset_…"
    ],
    "status": "pending"
  },
  "usage": {
    "credits": 400,
    "balance": 1880,
    "requestId": "req_…"
  }
}

GET

/video/statusSOONfree

Poll a video job. Free.

Request

curl https://ovmmedia.com/api/v1/video/status?assetId=... \
  -H "Authorization: Bearer $FORGE_API_KEY"

Response

{
  "data": {
    "status": "done",
    "url": "https://cdn.ovmmedia.com/…mp4"
  },
  "usage": {
    "credits": 0,
    "balance": 1880,
    "requestId": "req_…"
  }
}