Publish a service

POST/v1/services

Creates a service, or updates the existing one with the same slug under your ownership.

The slug identifies the service permanently. Changing a slug creates a second service rather than renaming the first.

Publishing is idempotent. Sending an unchanged definition returns 200 with unchanged: true and writes nothing, which is what makes varis publish safe to run on every deploy.

Requires a signed-in developer who is a member of the owner named in X-Varis-Owner-Identifier. The published service is attributed to that person.

Headers

AuthorizationBearer <token>required

A device token, prefixed var_dt_, issued by varis login to one machine and stored there. Identifies the human; carries no permissions of its own. Expires 180 days after its last use, and can be revoked from the dashboard.

X-Varis-Owner-Identifierstringrequired

The owner the developer is acting for, from varis.json. Only accepted when the device token's user is a member of it.

Body

application/json

slugstringrequired

Unique within your ownership, and permanent. Republishing the same slug updates that service; a new slug creates a second one.

namestringrequired

descriptionstringrequired

Required, and the highest-leverage field you write. An agent reads it to decide whether to call you, and it is half the search index. Name the capability and its inputs in plain words.

instructionsstring

Optional. How an agent should use the service, when the input fields alone don't say: another service to call first, or where a value comes from. Agents read it with the description before calling. Publishing is declarative, so omitting it, or sending an empty string, removes any instructions already stored.

service_typeenum<string>required

What shape of thing this is, as opposed to what domain it is about. Categories answer the domain question. A market data feed is service_type data with categories finance, media, and politics.

Available options: data, content, tool, skill, compute, memory, storage, model, messaging

categoriesenum<string>[]required

Category slugs, at least one. A service with no categories is undiscoverable, so an empty list is an error rather than "all".

Unlike service_type, these are a closed list the platform defines. An unknown slug is a 400.

Available options: accounting, advertising, aerospace, agents, agriculture, ai, analytics, animation, apis, architecture, art, astrology, astronomy, audio, audio-processing, authentication, automation, automotive, aviation, banking, beauty, biology, biotech, blockchain, books, branding, browser-automation, business-intelligence, calendar, careers, census, charity, chemistry, civil-engineering, climate, clinical-trials, cloud, code-generation, code-review, collaboration, comics, commodities, compliance, computer-vision, construction, consulting, contracts, copywriting, credit, crm, crypto, culture, customer-support, databases, datasets, dating, defense, demographics, design, developer-tools, devops, diy, documents, earth-science, ecology, ecommerce, economics, education, elections, electrical-engineering, email, embeddings, employment, energy, entertainment, environment, esports, evaluation, events, family, fashion, file-conversion, film, finance, fitness, food, forex, fraud-detection, gaming, gardening, genealogy, genomics, geolocation, geopolitics, geospatial, governance, government, graphic-design, hardware, health, healthcare, higher-education, history, home, hospitality, housing, human-resources, human-rights, humor, identity-verification, image-generation, image-processing, immigration, infrastructure, insurance, intellectual-property, international-relations, inventory, investing, invoicing, iot, journalism, k12, knowledge-base, kyc, language-learning, law-enforcement, legal, lending, lifestyle, llm, localization, logistics, machine-learning, manufacturing, maps, maritime, market-research, marketing, marketplace, materials-science, mathematics, mechanical-engineering, media, medical-imaging, medicine, mental-health, military, mobile-development, monitoring, mortgage, music, networking, news, nlp, nonprofit, notifications, nutrition, observability, ocr, oil-and-gas, open-data, open-source, outdoors, parenting, patents, payments, payroll, pdf, personal-finance, pets, pharmaceuticals, philosophy, photography, physics, podcasts, policy, politics, pricing, privacy, procurement, productivity, project-management, prompts, psychology, public-health, public-records, public-relations, public-safety, public-transit, publishing, quantum-computing, real-estate, recipes, recruiting, reference, relationships, religion, renewable-energy, research, restaurants, retail, robotics, sales, sanctions, scheduling, science, scraping, search, security, semiconductors, seo, shipping, shopping, small-business, sms, social-media, sociology, software-engineering, space, speech, sports, startups, statistics, stocks, supply-chain, sustainability, tax, telecommunications, television, testing, text-to-speech, ticketing, time-series, trading, transcription, translation, transportation, travel, ui-design, urban-planning, utilities, vector-search, venture-capital, veterinary, video, video-processing, weather, web-development, web3, wellness, writing

endpoint_urlstring<uri>required

Must be HTTPS and publicly reachable. Varis signs every request to it with Ed25519. Verify with the public key at /.well-known/varis-signing-keys.

A localhost address is rejected at publish time rather than failing silently on every invocation.

No query string or fragment. For a GET service, the input becomes the query string, so declare query values as input_schema properties instead.

methodobject

Defaults to GET. Publishing is declarative, so omitting it on a republish sets GET even if the service was POST.

Default: "GET"

price_centsinteger

Your price per request, in US cents. An integer, as with every financial API. Defaults to 0, which makes the service free. Agents pay this plus the 5% Varis fee, and you receive all of it.

Varis settles internally in credits at 100 credits per cent, which is why the fee on a one cent call still reconciles exactly.

Default: 0

versionstring

Recorded, not resolved. Invocations always hit the current definition; there is no version selection in this release. The field exists so published definitions carry one from the start.

Default: "1.0.0"

statusobject

Defaults to published. Send draft to register without going live.

Default: "published"

input_schemaobjectrequired

JSON Schema, with a top-level type. Validated before the provider is called, so a malformed input never reaches you and never costs the caller anything.

For a GET service, a top-level type of object whose properties are all flat. See ServiceMethod.

output_schemaobjectrequired

JSON Schema, with a top-level type. A response that violates it fails the invocation and reverses the charge, so declare what you actually return.

Response

application/json

The service already existed. It was updated, or nothing changed.

idstringrequired

Pass this to /v1/invoke, not the slug.

slugstringrequired

namestringrequired

descriptionstringrequired

instructionsstring | nullrequired

How to use the service, from its provider. Read it before invoking: it may name another service to call first. null when the provider gave none.

service_typeenum<string>required

What shape of thing this is, as opposed to what domain it is about. Categories answer the domain question. A market data feed is service_type data with categories finance, media, and politics.

Available options: data, content, tool, skill, compute, memory, storage, model, messaging

provider_namestring

The publishing owner's display name.

versionstring

categoriesenum<string>[]

input_schemaobjectrequired

output_schemaobjectrequired

statusenum<string>required

draft is not discoverable and not invocable. published is both. disabled stops new invocations without removing the service from anyone's transaction history.

Available options: draft, published, disabled

endpoint_urlstring<uri>

Returned only to the service's own owner.

methodobject

Returned only to the service's own owner.

created_atstring<date-time>

updated_atstring<date-time>

price_centsintegerrequired

Your price per invocation, in US cents. Agents pay this plus the 5% Varis fee; you receive all of it.

unchangedbooleanrequired

True when the submitted definition matched what was already stored, in which case nothing was written and updated_at did not move. Always false on a 201.

curl -X POST 'https://api.usevaris.com/v1/services' \  -H 'Content-Type: application/json' \  -d '{  "slug": "string",  "name": "string",  "description": "stringstringstringst",  "service_type": "data",  "categories": [    "accounting"  ],  "endpoint_url": "http://example.com",  "input_schema": {},  "output_schema": {}}'

{  "id": "string",  "slug": "string",  "name": "string",  "description": "string",  "instructions": "string",  "service_type": "data",  "provider_name": "string",  "version": "string",  "categories": [    "accounting"  ],  "input_schema": {},  "output_schema": {},  "status": "draft",  "endpoint_url": "http://example.com",  "method": "GET",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z",  "price_cents": 0,  "unchanged": true}