Services on Ouro

Last updated 14d ago

Adding new functionality to Ouro via APIs

Services let you bring external capabilities into Ouro by connecting a web‑accessible API. A Service is a set of Routes (endpoints that share a base URL) plus configuration like authentication and metadata. Once added, teammates can call your endpoints, chain them with other assets, and build workflows in the Water layer.

Creating a Service

Use the create form to register an API. Ouro currently supports REST APIs via an OpenAPI spec (JSON or YAML). You can provide your spec in two ways:

Upload a file - Upload a local .json or .yaml file containing your OpenAPI specification
Provide a URL - Enter a URL to your hosted OpenAPI spec (e.g., https://api.example.com/openapi.json)

When you import a spec, we extract the base URL, routes, request/response schemas, and auth hints so your API is callable immediately. For URL-based specs, we fetch and store a copy in our database for fast access.

If you generate your spec with FastAPI, the OpenAPI document is exposed at /openapi.json. You can use this URL directly when creating a service. See the API docs for programmatic access.

Routes

Routes are the building blocks of a Service. Each Route describes the HTTP method, path, parameters, expected body and headers, and the response shapes. Good descriptions in your spec become in‑product docs, making it easy for others to discover and use your API.

Typing inputs and outputs (side effects)

Services can either call the Ouro API directly (you manage reads/writes) or let Ouro handle asset I/O by declaring expected input and output asset types per Route. The latter enables validation, linking, and composability across assets.

/transform/transcribe:
  post:
    summary: Transcribe audio to text
    x-ouro-input-asset-type: file
    x-ouro-input-asset-filter: metadata->type.in.(audio/mpeg,audio/wav)
    x-ouro-output-asset-type: post

Retrieving the OpenAPI Specification

Once a service is created, you can retrieve its stored OpenAPI specification programmatically:

Via the Python SDK: Use service.read_spec() to get the spec as a JSON object
Via HTTP: Send a GET request to /services/{service_id}/spec

The spec is stored in our database and remains stable even if the original remote spec changes. This ensures consistency and fast access without needing to fetch from remote URLs on every request.

Authentication

For protected APIs, add credentials so Ouro can authenticate requests on behalf of the user:

None (public)
Personal Access Token (sent in Authorization header)
Ouro Service Secret (validate Authorization: Basic <token>)

When you choose Ouro authentication during service creation, the platform issues a secret token. Configure your API to only respond when this header is present and valid. See the Ouro as API middleware guide on verification.

Need another auth method? Contact us and we’ll prioritize it.

Hosting and availability

Your API must be reachable from the public internet. Any modern hosting works (serverless, managed platforms, or your own infra). We recommend Modal for serverless deployments, especially for ML workloads. Keep latencies low and document quotas; those details help others compose reliable pipelines.

Linking and discovery

Services benefit from asset linking: reference relevant files, datasets, or posts so users have context and examples. Rich metadata improves search and recommendations across the platform.

By declaring routes clearly, typing I/O when appropriate, and enabling auth, your Service becomes a reusable building block that teams can compose alongside files, datasets, and posts.

Datasets Posts