Publish a service

This page explains how to describe your service to Varis and publish it. If you want the shortest path, see Quickstart: publish a service.

Before you beginCopy Anchor Link

• Create a Varis account.
• Deploy your endpoint to a public https address.
• Add verifyRequest to your endpoint. For more information, see Handle requests.

Service fieldsCopy Anchor Link

Every service has the same fields, whether you publish from the dashboard or with the CLI.

Publish your serviceCopy Anchor Link

Declare services in codeCopy Anchor Link

This section applies to the CLI only.

I/O TypesCopy Anchor Link

The CLI turns your Input and Output types into JSON Schemas when you publish. Write both type arguments. TypeScript can't infer them, and the build fails without them.

You can use strings, numbers, booleans, null, literals and literal unions, arrays, objects, optional fields, index signatures, and unions of those. A field marked with ? is optional. Every other field is required.

If your service takes no input, use void as the input type:

varis.services.define<void, Output>({
  // ...rest of the service definition.
  })

CommentsCopy Anchor Link

Comments on your fields become descriptions in the schema, and agents read them. Write them for agents. A comment above the field or at the end of its line works, in any comment style.

type Input = {
  /** ISO 4217 code of the currency to convert from. */
  from: string;
  // ISO 4217 code of the currency to convert to.
  to: string;
  amount: number; // The amount to convert.
}

A comment above the Input or Output type describes the whole schema.

/** Pass the argument: 
 * `from` and `to`: ISO 4217 code of the currencies. 
 * `amount`: integer in the lowest denomination of the `from` currency. 
 * */
type Input = {
  from: string;
  to: string;
  amount: number;
}

To keep a comment out of your published service, leave a blank line between the comment and the field or type. Use this for internal notes, such as TODOs, that agents shouldn't see.

type Input = {
  // TODO: add support for historical rates.

  /** ISO 4217 code of the currency to convert from, such as USD. */
  from: string;
  // ..
};

Agents see the description of from. They don't see the TODO.

Literal valuesCopy Anchor Link

The CLI reads define from your source code. It doesn't run your code. Every value you pass to define must be written out in full. An environment variable or any other computed value fails the build, and the CLI tells you the file and line.

Endpoint addressCopy Anchor Link

Varis needs a full endpoint URL for every service. You give it one in either of two ways:

• endpoint_url: the full address, such as https://api.example.com/currency/convert. Varis uses it as written.
• path: only the path, such as /currency/convert. Varis joins it to the base_url in varis.json to build the endpoint URL.

Use path if your services share one host. The set base_url allows you to change the host in one place instead of in every define call.

To set base_url, run:

varis init --base-url https://api.example.com

If you set endpoint_url on a service, Varis uses it and ignores path and base_url for that service. This lets you point one service at a different host.

If you set path but varis.json has no base_url, varis build fails.

Publish one serviceCopy Anchor Link

To publish only one service from a project with several, pass its slug:

varis publish convert-currency

varis.jsonCopy Anchor Link

The first time you run varis publish, the CLI creates varis.json and writes your services to it. Commit it with your code. It contains your owner's ID, which isn't a secret, and it never contains a credential.

For more information, see varis.json.

Choose GET or POSTCopy Anchor Link

The method decides how your input reaches your endpoint.

Use GET if your endpoint already reads query parameters and your input is flat. Use POST if your input is nested or contains anything sensitive.

For GET, an array repeats its key, such as ?tag=a&tag=b. Varis sends only the fields declared in your input schema, and it leaves out null values and empty arrays.

Endpoint rulesCopy Anchor Link

Varis accepts an endpoint URL only if it meets these rules:

• It uses https.
• It's publicly reachable. Varis rejects localhost and private addresses.
• It has no query string or fragment. Declare query values as input fields instead.

Varis never follows redirects. A redirect counts as a failed call, and the agent isn't charged. Publish the final address. Common causes of redirects are a trailing slash, http to https, and www to the bare domain.

To test against localhost before you publish, see Local development.

What's nextCopy Anchor Link

• Handle requests: what Varis sends to your endpoint and what it expects back.
• Update a service.