Endpoint reference

Creator catalog and placements

Guest reads are separate from protected participant operations. Paths below are relative to https://api.vibevo.io/api/v1.

Guest catalog

GET /creator-catalog accepts q, channelType (STREAMER or SOCIAL), platform, format, topic, language, geo, audienceGeo, minPriceCents, maxPriceCents, availability, sort (price, relevance, activity), limit (1–100), and cursor. audienceGeo is an ISO country code from a positive share in the latest current verified audience distribution; lowercase input is normalized to uppercase. The legacy geo filter remains a creator profile tag. platform and audienceGeo must match the same active published service channel. Price sorting and its cursor use the creator’s minimum published service price, which can differ from the service selected by the filters. The only accepted availability value is AVAILABLE; the filter uses published services. Order dates and “by agreement” are not availability filters.

curl 'https://api.vibevo.io/api/v1/creator-catalog?channelType=STREAMER&availability=AVAILABLE&limit=20'

# Anonymous response (public fields only)
{
  "data": [{
    "publicId": "d8e805e4-1ec5-4ab6-a734-4ea389cecc6c",
    "metricsObservationId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "lastModified": "2026-10-08T12:00:00.000Z",
    "displayName": "Streamer One",
    "topics": ["gaming"],
    "languages": ["en"],
    "channelType": "STREAMER",
    "channels": [{"platform":"TWITCH","handle":"streamer_one","canonicalUrl":"https://www.twitch.tv/streamer_one"}],
    "services": [{
      "serviceListingId": 7, "type": "STREAM", "variant": "MENTION",
      "channel":{"platform":"TWITCH","handle":"streamer_one","canonicalUrl":"https://www.twitch.tv/streamer_one"},
      "proofModes":["PUBLIC_VOD"],
      "title": "Product mention", "unit": "broadcast",
      "basePrice": {"raw":"100000000","currency":"USDT","decimals":6},
      "packageOptions": [{"quantity":1,"discountBps":0,"packageBase":{"raw":"100000000","currency":"USDT","decimals":6}},{"quantity":5,"discountBps":500,"packageBase":{"raw":"475000000","currency":"USDT","decimals":6}}]
    }],
    "metrics": []
  }],
  "nextCursor": null
}

GET /creator-pages/{publicId} returns a page while the creator has published it and it has available services with usage terms. Otherwise the API responds 404 with code RESOURCE_NOT_FOUND. Pre-publication review of the profile, prices, services, or manual URL is not required. Drafts, contacts, proof files, schedules, and fee fields are omitted. Unpublishing revokes page availability, HTML, Open Graph, cache, and sitemap entries; unpublished pages are not indexed.

Public response and prices

The catalog shows the published service base price, without fees or creator earnings. A money value is {raw, currency: "USDT", decimals: 6}; raw is an integer number of USDT micro-units. For example, raw "100000000" means 100 USDT. Requests send priceCents as an integer cents string; a USDT price input has at most two decimal places.

For a connected verified social account, channels[].audience may contain verified geography, age and gender for that exact account: source, capturedAt, verifiedAt, periodDays, geo and demo. Average views use known non-negative view counts from the latest five public posts. Manual channels have no trusted audience metrics; missing data stays unavailable, never zero. Private snapshot/evidence/connection IDs are omitted.

Protected participant flow

Every path in this list has the /public prefix and requires an API key: GET requests need read; mutations need write plus current role and object permissions.

• Creator: GET/PATCH /public/influencer-profile; GET /public/influencer-profile/page; POST /public/influencer-profile/page/generate, /submit, /page/publish, and /page/unpublish; GET/POST /public/influencer-channels; GET/PUT /public/influencer-channels/{id}/pricing; POST /public/influencer-channels/{id}/ownership-challenge, /ownership-uploads, /ownership-uploads/{uploadId}/complete, /ownership-evidence, and /submit. Profile, page, channel, ownership, and pricing routes also have JWT twins under /api/v1 without /public. GET/PUT /public/influencer-accounts/{accountId}/pricing remains a compatibility alias for the owner’s active, verified social account; channel pricing is canonical. The compatible publishAfterApproval field is boolean: true publishes the current version immediately without pre-publication review; false only generates a private preview. Manual channels accept a safe public HTTPS URL for any permitted platform; legacy handle-only input remains supported for Twitch/Kick. Ownership verification is optional and does not block publication or purchase. Native accounts must remain active, verified, owned by the creator, unblocked, unsuspended, unsold, and undeleted. The JWT-only POST /api/v1/creator/social-accounts/{id}/avatar/refresh refreshes an owner’s account avatar without a new OAuth flow and accepts no source URL in the body. Owner DTOs may include optional socialAccountId and avatarUrl. No MCP avatar tool is added.
• Advertiser: POST /public/placement-orders creates a draft; PATCH /public/placement-orders/{id} changes it; POST /public/placement-orders/{id}/quote prices it; POST /public/placement-orders/{id}/checkout confirms funding. Custom terms use POST /public/placement-offers/quote and POST /public/placement-offers. Read orders and analytics with GET /public/placement-orders, GET /public/placement-orders/{id}, GET /public/analytics/placements, and GET /public/placement-orders/{id}/analytics.
• After funding, order parties use GET /public/placement-assignments, GET /public/placement-assignments/{id}, /events, and /deliverables; actions include accept, decline, submit, approve, request-changes, cancel, issues, and change-proposals (propose/accept a new due date). Update a result with PUT /public/placement-assignments/{id}/deliverables/{deliverableId}; private uploads support create/complete and attached-result download. JWT twins use the same routes under /api/v1 without /public. Staff use separate JWT-only review routes.

If publication is temporarily disabled, an explicit publish request saves its intent and returns 503 WRITE_NOT_AVAILABLE_FOR_FEATURE. After the release control is enabled, retry the same request with the same UUID Idempotency-Key. This does not create staff review; existing published pages remain available and unpublish still works.

Create an order

curl -X POST 'https://api.vibevo.io/api/v1/public/placement-orders' \
  -H "Authorization: Bearer $VIBEVO_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7ddc2979-9a7f-4d4f-8f89-38ea3353e444' \
  -d '{"items":[{"serviceListingId":7,"quantity":1,"discountBps":0,"dueAt":"2026-10-20T18:00:00.000Z","brief":"Mention the product during the broadcast.","results":[{"expectedAt":"2026-10-20T17:00:00.000Z"}],"rights":{}}]}'

results must contain exactly as many obligations as selected placements (1, 5, or 10); expectedAt is each publication date and dueAt is the overall deadline. rights carries the agreed usage terms.

Quote and confirmation

POST /api/v1/public/placement-orders/{id}/quote
Idempotency-Key: <stable UUID>
{ "expectedVersion": 1 }

# Advertiser-safe quote projection
{
  "data": {
    "quoteId": "9e955328-7a2b-42a4-9963-330fcc83ad92",
    "quoteVersion": 1, "orderId": 14,
    "expiresAt": "2026-10-08T12:10:00.000Z",
    "payloadHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "currency": "USDT",
    "items": [{"serviceListingId":7,"base":{"raw":"100000000","currency":"USDT","decimals":6},"brandFee":{"raw":"5000000","currency":"USDT","decimals":6},"total":{"raw":"105000000","currency":"USDT","decimals":6}}],
    "totals": {"base":{"raw":"100000000","currency":"USDT","decimals":6},"brandFee":{"raw":"5000000","currency":"USDT","decimals":6},"total":{"raw":"105000000","currency":"USDT","decimals":6}}
  }
}

POST /api/v1/public/placement-orders/{id}/checkout
Idempotency-Key: <new stable UUID>
{ "quoteId": "9e955328-7a2b-42a4-9963-330fcc83ad92", "quoteVersion": 1, "payloadHash": "<copy the quote hash>", "confirm": true }

A quote returns the creator base amount, the brand’s fee, and the total reserve to the advertiser only. The client displays these amounts and explicitly confirms checkout with quoteId, quoteVersion, payloadHash, and confirm:true. The creator’s fee and net earnings are omitted from advertiser DTOs. The creator’s own pricing response contains the base amount, creator fee, and net earnings; it omits the brand fee.

Private UGC custom-offer example

POST /api/v1/public/placement-offers/quote
Idempotency-Key: <stable UUID>
{
  "origin": "CUSTOM",
  "creatorPublicId": "d8e805e4-1ec5-4ab6-a734-4ea389cecc6c",
  "serviceType": "UGC",
  "proofModes": ["PRIVATE_FILE"],
  "priceCents": "12000",
  "expectedEndAt": "2026-10-20T18:00:00.000Z",
  "quantity": 1,
  "discountBps": 0,
  "brief": "Create and deliver a short private product video.",
  "results": [{"expectedAt":"2026-10-20T17:00:00.000Z","description":"Deliver the private video"}],
  "rights": {"usage":"As agreed in the brief"}
}

# Quote response: { data: { quoteId, quoteVersion, payloadHash, items: [{ serviceListingId: null, base, brandFee, total }], totals, ... } }

POST /api/v1/public/placement-offers
Idempotency-Key: <new stable UUID>
{ "quoteId": "<quote ID>", "quoteVersion": 1, "payloadHash": "<quote hash>", "confirm": true }

# Without serviceListingId, only UGC + PRIVATE_FILE is accepted; do not send accountId or channelRef.

When serviceListingId is omitted, only serviceType "UGC" with proofModes ["PRIVATE_FILE"] is accepted. Do not send accountId or channelRef. The quote shows the base amount, brand fee, and total reserve and has serviceListingId null. A FILE result has null channelRef and publishedRevision; url and contentId are null and metrics is empty. It has no public URL or social metrics.

Retries and errors

A UUID Idempotency-Key is required for profile PATCH, page/generate, channel create, pricing PUT, and the order, assignment, and ownership mutations that specify it in their contracts. For an unknown result, retry the same method, path, UUID, and body; reusing a key with another body/action/target returns IDEMPOTENCY_CONFLICT. Fresh role and ownership checks run before replay. Profile PATCH returns its saved DTO, while page/generate rebuilds the preview. Pricing PUT returns the saved operation/version with a fresh current projection; replay does not repeat a money operation or price change.

Structured errors

Error responses include a stable code and safe message. Possible codes include API_KEY_INVALID (401), API_KEY_MISSING_SCOPE / ROLE_NOT_ALLOWED / ACCOUNT_ACCESS_DENIED (403), RESOURCE_NOT_FOUND (404), INVALID_MONEY_PRECISION / INVALID_PROOF (400), VERSION_CONFLICT / QUOTE_EXPIRED / PRICE_CHANGED / IDEMPOTENCY_CONFLICT / INSUFFICIENT_FUNDS (409), RATE_LIMITED (429), and SERVICE_UNAVAILABLE / PRIVATE_UPLOAD_SERVICE_UNAVAILABLE (503). A foreign or inaccessible object appears as not found.

Example of a safe error body:

{"code":"IDEMPOTENCY_CONFLICT","message":"The idempotency key was used with a different payload."}