canonical: https://jentic.com/apis/openlinksw.com/openlinksw-osdb

# Openlinksw OSDB REST API v1

The OpenLink Smart Data Bot (OSDB) REST API v1 lets clients enumerate, load, and unload conversational services and invoke their actions over HTTP. Each service exposes a set of named actions with help and parameter schemas, and the `/api/v1/actions/{serviceId}/{actionId}/exec` endpoint runs the action and returns the result. Authentication is handled by login and logout endpoints, and the API is the programmatic surface behind OpenLink's Smart Data Bot tooling.

## For AI agents

Discover, load, and execute OpenLink Smart Data Bot services and their actions to drive conversational data workflows over HTTP.

## Scope

Does not handle data ingestion, model training, or vector storage - use for OpenLink Smart Data Bot service and action invocation only.

## Capabilities

- List the Smart Data Bot services currently available on the OSDB instance
- Load a service so its actions can be invoked by clients
- Inspect the action set for a loaded service, including help text and parameters
- Execute a named action on a service and receive its structured result
- Unload a service when it is no longer needed to free resources
- Authenticate a session via login and end it via logout

## Use cases

### Programmatic Smart Data Bot Action Execution

Drive an OpenLink Smart Data Bot from a custom UI or automation by listing services, loading the one needed, then calling its actions through POST `/api/v1/actions/{serviceId}/{actionId}/exec.` The action's parameter schema is discoverable via the help endpoint, so clients can build dynamic forms or agent prompts without hard-coded shapes.

Example prompt: Load the service 'sql-agent', list its actions, and execute the action that takes a SQL query parameter against a target dataset, then return the action's response.

### Service Lifecycle Management

Operators can manage which Smart Data Bot services are loaded on a host using POST and DELETE on `/api/v1/services.` This is useful when deploying a new service version or when conserving resources by keeping only currently used services loaded.

Example prompt: Unload the service with ID 'demo-bot' via DELETE `/api/v1/services/{serviceId}` and confirm via GET `/api/v1/services` that it no longer appears in the loaded list.

### Action Discovery for an Agent UI

Build an agent UI that introspects available services and their actions on the fly, presenting users with the operations they can run. The agent calls GET `/api/v1/services` to list services, then GET `/api/v1/actions/{serviceId}` to enumerate actions, and uses /help to surface human-readable parameter descriptions.

Example prompt: List loaded services, pick the first one, list its actions, and render each action's help text so a user can choose one to run.

### AI Agent Tool Use via Jentic

An LLM agent can treat OSDB actions as tools, discovering them through Jentic and calling exec endpoints with structured arguments. Jentic returns the action's input schema so the agent does not have to parse OpenAPI, and the call result is forwarded back to the agent as part of its reasoning trace.

Example prompt: Use Jentic to search for 'execute an osdb action', load the exec operation for the chosen serviceId and actionId, and run it with the supplied JSON arguments.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/services` | List loaded services |
| POST | `/api/v1/services` | Load a service |
| DELETE | `/api/v1/services/{serviceId}` | Unload a service |
| GET | `/api/v1/actions/{serviceId}` | List actions for a service |
| POST | `/api/v1/actions/{serviceId}/{actionId}/exec` | Execute a named action |
| GET | `/api/v1/actions/{serviceId}/{actionId}/help` | Get help and parameter info for an action |

## Key resources

- **Services** — List, load, describe, and unload Smart Data Bot services.
- **Actions** — List, describe, get help for, and execute named actions on a loaded service.
- **Session** — Log in and log out of the OSDB instance to manage a session.

## Why Jentic

- **Setup:** Wiring the OSDB REST API by hand means managing its session login and logout flow against osdb.openlinksw.com and threading the session through each Smart Data Bot service and action call. Through Jentic you install once, import the OSDB REST API from the API Directory, store the login credentials once, and your agent calls it.
- **Permission scoping:** OSDB puts the service id in the URL path (`/api/v1/actions/{serviceId}`), so a rule can pin your agent to one service: it can list and run actions for that service and nothing else. You choose the operations it may call, so destructive ones like deleting a service are not included unless you add them.
- **Credential handling:** Your OSDB login credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list OSDB services' or 'execute an OSDB action', and Jentic returns the matching operation with its parameter schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **OSDB REST API v1 (alt)** — A second packaging of the same OSDB v1 surface; identical operations under a different api_slug.
- **Pinecone API** — Pinecone provides vector storage that an OSDB action could query as a downstream step in a data workflow.
- **Elastic API** — Elastic offers full-text and analytics search; OSDB actions can be designed to call it as a backing store.

## FAQ

### What authentication does the OSDB REST API use?

The OSDB API exposes GET `/api/v1/login` and GET `/api/v1/logout` endpoints to manage a session and the spec does not declare a securityScheme, so no API key is required to call most endpoints. Through Jentic, any session token returned by login can be vaulted and replayed automatically.

### Can I execute a Smart Data Bot action over HTTP with the OSDB REST API?

Yes. POST `/api/v1/actions/{serviceId}/{actionId}/exec` runs the named action on the loaded service and returns its result. Use the /help endpoint on the same path to retrieve parameter documentation before constructing the request body.

### What are the rate limits for the OSDB REST API?

OSDB is typically self-hosted by OpenLink customers, so rate limits depend on the host's deployment. The published spec does not declare a hard limit; treat it as fair-use against the running instance and check with the operator for production quotas.

### How do I list available services with the OSDB REST API through Jentic?

Search Jentic for 'list openlink smart data bot services', load GET `/api/v1/services`, and execute it. Jentic returns the structured list of services along with their identifiers.

### What is the difference between loading and executing a service in the OSDB REST API?

Loading a service via POST `/api/v1/services` makes its actions available on the host. Executing an action via POST `/api/v1/actions/{serviceId}/{actionId}/exec` runs the chosen action with input parameters. A service must be loaded before its actions can be executed.

### Can I limit what my agent is allowed to do with the OSDB REST API?

Yes. Because Jentic One is self-hosted by you, your own rules decide which OSDB operations and credentials your agent may use. Since OSDB carries the service id in the URL path (`/api/v1/actions/{serviceId}`), you can pin the agent to a single service so it only lists and executes actions for that service via POST `/api/v1/actions/{serviceId}/{actionId}/exec` and reads help via `/api/v1/actions/{serviceId}/{actionId}/help.` Destructive operations such as unloading a service with DELETE `/api/v1/services/{serviceId}` are excluded unless you explicitly grant them.