OpenAPI and interactive docs

Every published service documents itself. This page covers the interactive documentation under API → Reference, the OpenAPI file you can download, and how to use that file in Postman or a code generator.

What you get

• Interactive docs (Interaktive Doku): the service's API as a readable page, with every input, its type and rules, the shape of the answer and the possible errors.
• The OpenAPI file: the same description as a file in the OpenAPI 3.0 format, as JSON or YAML. Tools such as Postman, Insomnia and code generators read it.
• Errors (Fehler): a table of what a call answers when it does not succeed.

All three are generated from the published service. They always match what the service really accepts.

Open the interactive docs

1. Open the published service.
2. Go to API → Reference (Referenz) → Interactive docs.
3. Open Calculate (GET) or Calculate (POST) to see the parameters, an example request and an example answer.

The page shows:

• The service name, its description and the per-minute limit.
• Each input with its name, type, whether it is required, its default, its minimum and maximum, and its allowed values.
• The answer schema, with your outputs listed by name and description.
• The error answers 400, 404, 429 and 500.
• For a token-protected service, how the token is sent.

A filter field at the top narrows the list. Try it out on an operation sends a real call to your service; it counts like any other call.

Download the OpenAPI file

On the same page, at the top right:

• JSON downloads the file as JSON.
• YAML downloads it as YAML.
• Copy Spec URL (Spec-URL kopieren) copies the address of the file, for tools that import from an address.

The address of the file is:

https://spreadapi.io/api/v1/services/{serviceId}/openapi
https://spreadapi.io/api/v1/services/{serviceId}/openapi?format=yaml

For a public service anyone can read this address. For a token-protected service it needs a token of the service: add ?token=<token> or send Authorization: Bearer <token>. As the owner you can always download the file from the app while signed in.

Use it in Postman or Insomnia

1. Download the file, or copy the spec address.
2. In Postman choose Import and pick the file or paste the address. Insomnia has the same kind of import.
3. The tool creates the two requests, GET and POST, with all inputs filled with example values.
4. For a protected service, set the token as a Bearer token in the tool's authorization settings.

Use it with a code generator

OpenAPI generators turn the file into client code for many languages. Point the generator at the file or at the spec address. The generated client has one operation per method: executeServiceGET and executeServicePOST.

The same file is what OpenAPI-based connectors use; see Power Automate.

After you change the service

The documentation and the file follow the published service. After you republish with new or renamed inputs or outputs, download the file again and re-import it into your tools. Collections and generated clients do not update by themselves.

The Errors page

API → Reference → Errors lists what a failed call answers: the HTTP status, the text in error, what it means and what to do. A note there says that token and calculation problems answer with HTTP 400, not 401 or 500. The complete list with explanations is in the Error reference.

Limits

• The docs and the file exist for published services. The API tab is locked for a draft.
• The file describes the calculate address with GET and POST. Batch calls are described in Batch calls.
• The file documents the JSON, CSV and plain-text answers of GET; CSV and plain text are not available on POST.

Related

• Call a service over the API
• The API response
• Code examples

For developers and agents

Reading the spec:

• The inputs are under paths[...].post.requestBody.content["application/json"].schema.properties.inputs.properties, with type, minimum, maximum, enum, default and description. required lists the required input names.
• Input types map to number, integer, boolean or string; a date is a string with format: date. A percentage input says in its description to send a decimal.
• A ready request is under requestBody.content["application/json"].examples.basic.value. It uses the service's own input names and values the service accepts.
• The outputs are named in the description of components.schemas.ExecutionResponse.properties.outputs.

Access to the spec address: a public service answers 200 for everyone. A token-protected service answers 401 without a valid token of the service. An unknown or unpublished service answers 404.

FAQ

Where is the documentation of my API?

Open the published service and go to API → Reference → Interactive docs. It lists every input, the answer and the errors of your service.

How do I download the OpenAPI file?

On API → Reference → Interactive docs, click JSON or YAML at the top right. Copy Spec URL copies the address of the file instead.

How do I import my service into Postman?

Download the OpenAPI file or copy its address, then use Import in Postman. Postman creates the GET and POST requests with example values.

Is the OpenAPI file public?

For a public service, yes: anyone with the address can read it. For a token-protected service the address answers 401 without a token of that service.

Does the OpenAPI file update when I change my service?

Yes, it is generated from the published version each time it is read. Tools that imported an older copy need a new import.

Can I generate a client library from it?

Yes. Any OpenAPI 3.0 generator can read the file or the spec address and produce client code with the operations executeServiceGET and executeServicePOST.

Does "Try it out" in the interactive docs make real calls?

Yes. It calls the published service, so the call counts toward the plan and appears in the usage numbers.

Why are the interactive docs empty for my service?

The documentation exists only for published services. Publish the service and open the page again.

As an agent, how do I learn a service's inputs before calling it?

Fetch https://spreadapi.io/api/v1/services/{serviceId}/openapi and read the inputs properties and the required list of the POST request body. The example under examples.basic.value is a request the service accepts.

Is the batch address part of the OpenAPI file?

No. The file describes the calculate address with GET and POST; batch calls are described in Batch calls.