canonical: https://jentic.com/apis/orcascan.com/orcascan

# Orca Scan REST API

Jentic publishes the only available OpenAPI specification for Orca Scan REST API, keeping it validated and agent-ready. The Orca Scan REST API reads and writes the rows, fields, and sheets of Orca Scan's barcode tracking system, so an application can record scanned items and keep an inventory sheet up to date. It exposes each sheet as a structured table of rows, lets you define the fields that make up a sheet, and fires webhooks when data changes. Change history is available per sheet and per row, and per-sheet user management controls who can see each tracking sheet.

## For AI agents

Record scanned barcodes as sheet rows, read and update inventory data, define the fields on a sheet, and register webhooks for changes in Orca Scan. Authenticates with an Orca Scan API key sent as a bearer token.

## Scope

Does not handle barcode image generation, label printing, or payment collection. Use for reading and updating Orca Scan sheet, row, and field data only.

## Capabilities

- Read the rows stored in a barcode tracking sheet
- Add rows as items are scanned and update a row when the same item is seen again
- Create, rename, and clear sheets for a tracking workflow
- Define and update the fields that make up a sheet
- Register webhooks that fire when a sheet's data changes
- Review the change history of a sheet or an individual row
- Control which users can access a given sheet

## Use cases

### Agent-Driven Barcode Capture

An AI agent connected through Jentic takes a scanned barcode and records it in an Orca Scan sheet, adding a new row or updating the existing one when the same item is scanned again. The agent can read the current rows first to check stock and then write the update, so a scanning workflow runs end to end without a human opening the Orca Scan app.

Example prompt: Add a row to the sheet named 'Warehouse Stock' with the scanned barcode and a quantity of 1, or increment the quantity if that barcode is already present

### Inventory Sheet Synchronisation

Applications keep an Orca Scan sheet in step with another system by reading its rows, adding new records, and updating changed ones through the row endpoints. Because each sheet defines its own fields, the integration reads the field definitions first so it maps incoming data onto the correct columns before writing.

Example prompt: Read every row on the parts sheet, then update the rows whose supplier field has changed and add rows for parts not yet listed

### Change Notification and Audit

Teams that need to react to sheet changes register a webhook on a sheet so Orca Scan posts an event when a row is added or edited, and they use the per-row and per-sheet history to audit what changed and when. This supports alerting on low stock or reviewing who last touched a tracked asset.

Example prompt: Create a webhook on the assets sheet for row-change events, then fetch the sheet history to list the last ten edits

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/sheets` | List sheets |
| POST | `/sheets/{sheetId}/rows` | Add or update rows |
| GET | `/sheets/{sheetId}/rows` | Get all rows on a sheet |
| PUT | `/sheets/{sheetId}/rows/{rowId}` | Update a single row |
| GET | `/sheets/{sheetId}/history` | Get sheet change history |
| POST | `/sheets/{sheetId}/hooks` | Create a webhook on a sheet |

## Key resources

- **Sheets** — Structured tables that hold tracked items; can be created, renamed, cleared, and deleted
- **Rows** — The records inside a sheet, added or updated as items are scanned and readable in bulk or singly
- **Fields** — The column definitions that give each sheet its schema
- **Hooks** — Webhook subscriptions that fire on supported sheet events

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 68 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 85 / 100
  - Developer Experience & Jentic Compatibility: 69 / 100
  - AI-Readiness & Agent Experience: 48 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 100 / 100
- **View full report:** https://jentic.com/apis/orcascan.com/orcascan/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the Orca Scan REST API by hand means handling its bearer token auth, learning how rows and fields map onto each sheet, and managing webhook subscriptions yourself. Through Jentic you install once, import Orca Scan from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Orca Scan puts the sheet id in the URL path, so a rule can pin your agent to one sheet: it can read and update rows on that sheet and nothing else. You choose the operations it may call, so destructive ones like deleting a sheet or removing a field are not included unless you add them.
- **Credential handling:** Your Orca Scan API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'add a scanned row to a sheet' or 'list rows in a sheet', and Jentic returns the matching Orca Scan operation with its input schema so the agent calls the right endpoint without reading the reference docs.

## Related APIs

- **Airtable API** — Spreadsheet-database that stores structured records in tables with a flexible field schema
- **Smartsheet API** — Work-management platform built on sheets with rows, columns, and collaboration features

## FAQ

### Why is there no official OpenAPI spec for Orca Scan REST API?

Orca Scan does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call the Orca Scan REST API via structured tooling. It is validated against the live API and kept up to date. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Is there an Orca Scan MCP server?

You don't need an MCP server to give your agent the Orca Scan REST API. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent can read and update sheet rows straight away, with no extra server to run and no tool definitions to load into the agent's context.

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

Yes. Because Orca Scan carries the sheet id in the URL path, you can write a rule that allows only the row read and row update operations on a single sheet, so the agent can log scans and adjust quantities for that sheet and touch nothing else, and every call it makes is logged.

### What authentication does the Orca Scan REST API use?

The Orca Scan REST API authenticates with a bearer token in the Authorization header per its OpenAPI spec, and that token is your Orca Scan API key. Through Jentic the key is stored encrypted by your own instance and added to each request at call time, so it never appears in the agent's prompt or logs.

### Can I record scanned barcodes into a sheet with the Orca Scan REST API?

Yes. The API adds rows to a sheet and updates an existing row when the same item is scanned again, so an agent can append each scan and keep quantities current. You can also read back every row on a sheet and review its change history.

### What are the rate limits for the Orca Scan REST API?

The OpenAPI spec does not specify rate limits for the Orca Scan REST API. For current limits and fair-use guidance, see the Orca Scan API documentation at https://orcascan.com/docs.

### How do I log a scanned item to Orca Scan through Jentic?

Import the Orca Scan REST API from the Jentic API Directory, then have your agent issue a request such as 'add a row to my parts sheet with this barcode'. Jentic matches the intent to the add-row operation and returns its input schema so the agent builds the correct request, with your stored API key injected at call time.