Reference

Every endpoint, and every way it says no.

Grouped by what you are trying to do rather than by internal service. Errors are documented as carefully as successes, because the error path is where an integration actually lives.

Authentication

One bearer token, sent on every request that is not purely public.

Header

Authorization: Bearer vs_live_…

Keys are scoped. A key with only listings:read can browse but cannot spend money, which is the right key to give an agent that is choosing between listings but not authorised to buy one.

Catalogue

Public. A key is optional, and raises your rate limit when present.

Method	Path	What it does	Auth
GET	`/api/listings`	Browse listings. Filter, sort, paginate.	Optional
GET	`/api/listings/:id`	One listing in full, including its data-flow declaration.	Optional
GET	`/api/listings/:id/schema`	The request and response schema for a callable listing.	Optional
GET	`/api/categories`	Fields, with a count of live listings in each.	Optional
GET	`/api/search`	Search listings and creators. `q` is required.	Optional

Calling a listing

Metered. Every call here appears on your invoice and in the creator's analytics.

Method	Path	What it does	Auth
POST	`/api/listings/:id/call`	Execute a tool call against a certified listing.	Key
POST	`/api/listings/:id/question`	Submit an async question. Answered within 48 hours or refunded.	Key

Trust and identity

The layer that makes a credential mean something to a caller.

Method	Path	What it does	Auth
GET	`/v1/profiles/:userId/trust`	Trust tier, verified credentials, weighted rating.	Optional
GET	`/v1/profiles/:userId/endorsements/summary`	Endorsement totals, broken down by domain.	Optional
GET	`/v1/skills/:skillId/creator-trust`	The creator trust block for one listing.	Optional
GET	`/v1/domains`	The domain tree used for expertise and discovery.	Optional

Buying

Your own subscriptions, usage and invoices.

Method	Path	What it does	Auth
POST	`/api/buyer/subscribe/:listingId`	Start a subscription.	Key
DELETE	`/api/buyer/subscribe/:listingId`	Cancel. Access runs to the end of the paid period.	Key
GET	`/api/buyer/subscriptions`	Everything you currently subscribe to.	Key
GET	`/api/buyer/usage`	Call history and running spend for the current period.	Key
GET	`/api/buyer/invoices`	Invoice history.	Key
POST	`/api/buyer/reviews`	Post a review. Requires a verified purchase.	Key

Selling

Managing your own listings, credentials and money.

Method	Path	What it does	Auth
POST	`/api/seller/listings`	Create a listing. Starts as a draft.	Key
PUT	`/api/seller/listings/:id`	Update a listing. Some fields re-trigger review.	Key
DELETE	`/api/seller/listings/:id`	Archive. Existing subscribers keep access to the end of their period.	Key
GET	`/api/seller/analytics`	Call volume, revenue and top callers.	Key
GET	`/api/seller/payouts`	Payout history and what is in transit.	Key
POST	`/api/seller/credentials`	Submit a credential for verification.	Key
GET	`/api/seller/questions`	Questions awaiting an answer, oldest deadline first.	Key
POST	`/api/seller/questions/:id/answer`	Answer a question inside its 48-hour window.	Key

Errors

Every error carries a stable code and a sentence written to be shown to a person.

Error body

{
  "error": {
    "code": "certification_expired",
    "message": "This listing's professional certification lapsed on 2 August 2026.",
    "listing_id": "l_hepatic",
    "docs": "https://vibestreet.io/docs/api-reference#errors"
  }
}

Codes

Status	Code	What it means
400	`schema_mismatch`	The body did not match the listing's declared request schema. The response names the field.
401	`no_key`	No key, or a key that has been revoked.
402	`payment_required`	The call is billable and there is no active subscription or valid payment method.
403	`tier_not_transactable`	The listing is Community tier and cannot be purchased or called.
403	`policy_blocked`	Your organisation's usage policy blocks this listing. The response names the policy.
404	`not_found`	No listing with that id or slug — or it is a draft you do not own.
409	`certification_expired`	The creator's credential lapsed. Existing calls fail rather than silently degrading.
429	`rate_limited`	Too many calls. `Retry-After` is always present on this one.
503	`upstream_unavailable`	The creator's endpoint did not respond. The call is not billed.

Rate limits and pagination

Predictable, and always stated in the response rather than only in these pages.

Headers on every response

Headers

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 594
X-RateLimit-Reset: 1787654400
Retry-After: 12          # only on 429

List endpoints take page and per_page, and return total and total_pages alongside the items. Maximum page size is 100.