canonical: https://jentic.com/apis/oracle.com/oracle-rest-data-services-api

# Oracle REST Data Services API

Oracle REST Data Services (ORDS) provides a REST interface to an Oracle Database, exposing tables and views as resources, hosting custom resource modules backed by SQL or PL/SQL handlers, and serving administrative endpoints for the database itself. It supports AutoREST for instant CRUD over schema objects, OpenAPI catalog generation, OAuth2 client management, and database environment introspection. ORDS sits between application code and the database, removing the need for a separate middle tier for many read and write paths.

## For AI agents

Query Oracle Database tables and views over REST, call custom ORDS resource modules, and manage ORDS OAuth2 clients and database administration endpoints.

## Scope

Does not handle Oracle Database backup, patching, or RMAN operations - use for REST access to schema objects, custom modules, and ORDS administration only.

## Capabilities

- Query and modify rows in Oracle Database tables exposed via AutoREST
- Retrieve a single row from a schema object by primary key
- Batch-load rows into a schema object through the batchload endpoint
- Invoke custom resource modules backed by SQL or PL/SQL handlers
- Inspect database environment status, version, and parameters
- Manage OAuth2 clients, tokens, and scopes for ORDS-published APIs

## Use cases

### Database-Backed Microservice Without a Middle Tier

Expose Oracle tables and views directly to a microservice through ORDS AutoREST instead of building a separate Java or Node service. The service consumes /{schema}/{object}/ endpoints for list and create and /{schema}/{object}/{id} for get and update, with consistent paging and filtering provided by ORDS.

Example prompt: GET /{schema}/{object}/ with query filters to page through rows, then PUT /{schema}/{object}/{id} to update the matching record

### Bulk Ingest into Oracle from External Pipelines

Use ORDS batchload to push large numbers of records from an external pipeline into Oracle without juggling JDBC drivers or running PL/SQL on a scheduled job. The batchload endpoint accepts payloads tuned for high-volume insert and is idempotent on the underlying object key.

Example prompt: POST /{schema}/{object}/batchload with a multi-row payload from the upstream pipeline

### Custom Resource Modules for Domain APIs

Expose business logic stored as PL/SQL packages or hand-tuned SQL through ORDS resource modules with /{schema}/{module}/{templatePath} URLs. This is how teams build domain-specific Oracle APIs without adding a separate application tier on top of the database.

Example prompt: GET /{schema}/{module}/{templatePath} to invoke the PL/SQL handler that serves a domain-specific report

### Database Operations and Health Checks

Operations teams can probe the Oracle Database environment, status, and configuration through the ORDS administration endpoints under `/admin/_/db-api/stable.` This pattern fits health dashboards and runbook automation that need to confirm a database is reachable and healthy without a SQL*Plus session.

Example prompt: GET `/admin/_/db-api/stable/database/status` from the ops dashboard every 60 seconds

### Agent-Driven Oracle Database Access via Jentic

An AI assistant for application teams can query and update Oracle tables through ORDS without holding raw database credentials. Jentic resolves natural-language intents like 'list orders for customer 123' to the right AutoREST or resource-module endpoint and executes against the configured ORDS instance.

Example prompt: Search Jentic for 'query an Oracle table by id', load the GET /{schema}/{object}/{id} operation, and execute against the ORDS instance

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/{schema}/{object}/` | List rows from a schema object |
| GET | `/{schema}/{object}/{id}` | Retrieve a row by primary key |
| POST | `/{schema}/{object}/batchload` | Batch load rows into a schema object |
| GET | `/admin/_/db-api/stable/database/status` | Get database status |
| GET | `/admin/_/db-api/stable/database/environment` | Get database environment metadata |
| GET | `/admin/_/db-api/stable/metadata-catalog/` | Retrieve the metadata catalog |

## Key resources

- **AutoREST Schema Objects** — Tables and views exposed automatically as REST resources
- **Batchload** — Bulk ingest endpoint for schema objects
- **Resource Modules** — Custom modules backed by SQL or PL/SQL handlers
- **Database Administration** — Database status, environment, and metadata endpoints
- **Metadata Catalog** — OpenAPI catalog of available resources
- **OAuth** — OAuth2 client and token management

## Why Jentic

- **Setup:** Wiring Oracle REST Data Services by hand means picking among basic, OAuth2, and bearer auth, pointing at your own {host}:{port}/ords deployment, and mapping AutoREST schema and object routes yourself. Through Jentic you install once, import Oracle REST Data Services from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** ORDS puts the schema and object in the URL path (/{schema}/{object}/...), so a rule can pin your agent to one schema and object: it can query and read rows there and nothing else. You choose the operations it may call, so a bulk batchload is not included unless you add it.
- **Credential handling:** Your ORDS basic, OAuth2 client, or bearer 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 'query an Oracle table' or 'check ORDS database status', and Jentic returns the matching AutoREST or admin operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Supabase REST API** — PostgREST-style auto-generated REST over Postgres rather than Oracle Database
- **MongoDB Atlas Data API** — Document-database REST API with a different data model than Oracle's relational tables
- **Snowflake SQL API** — Cloud data warehouse SQL API often paired with Oracle for analytics offload

## FAQ

### What authentication does the Oracle REST Data Services API use?

The spec declares Basic Auth, OAuth2, and Bearer token schemes. Production deployments typically use OAuth2 client credentials issued by ORDS, with Basic Auth available for administrative endpoints. Through Jentic, whichever credential type you configure is held encrypted in the vault and the agent only sees a scoped session.

### Can I expose any Oracle table as REST through this API?

Tables and views need to be REST-enabled in ORDS first (using ORDS.ENABLE_OBJECT in the database). Once enabled, /{schema}/{object}/ and /{schema}/{object}/{id} provide list, get, insert, update, and delete operations through AutoREST. The batchload endpoint covers bulk inserts.

### What is a resource module in ORDS?

A resource module is a named collection of REST endpoints backed by SQL or PL/SQL handlers, addressed at /{schema}/{module}/{templatePath}. This is how teams ship domain-specific Oracle APIs without adding a separate application tier.

### What are the rate limits for the Oracle REST Data Services API?

ORDS does not impose vendor-side rate limits - the API runs on customer-managed infrastructure. Practical throughput depends on the database and the ORDS server tier. Use connection pool sizing, table-level statistics, and Oracle's own resource manager rather than relying on API rate limits.

### Does ORDS publish an OpenAPI catalog of its endpoints?

Yes. `/admin/_/db-api/stable/metadata-catalog`/ returns a metadata catalog and ORDS can generate OpenAPI documents for resource modules. This lets clients introspect available paths without checking the database configuration directly.

### How do I query an Oracle table through Jentic?

Install the SDK with pip install jentic, then search for 'query an Oracle table by id'. Jentic returns the GET /{schema}/{object}/{id} operation; load it, supply the schema, object, and id, and execute. Run it through Jentic One, the self-hosted execution layer.

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

Yes. Because you run Jentic One yourself, your own rules decide which ORDS operations and credentials the agent may use. Since ORDS puts the schema and object in the URL path, a rule can pin the agent to a single schema and object so it only lists and reads rows from /{schema}/{object}/ and /{schema}/{object}/{id} and touches nothing else. You pick the operations it may call, so a bulk POST /{schema}/{object}/batchload or an admin status check is off limits unless you explicitly allow it, and your Oracle credentials are injected at execution time rather than exposed to the agent.