canonical: https://jentic.com/apis/collectiveaccess.org/collectiveaccess

# CollectiveAccess API

CollectiveAccess (Providence) is open-source collections management software used by museums, archives, and libraries. Its web service API provides JSON access to catalog items, search, browse, and metadata management on a self-hosted Providence installation. The API exposes 8 endpoints covering item CRUD, find and browse queries against any cataloging table, table model introspection, and media representation lookups, all authenticated with HTTP Basic credentials of a CollectiveAccess user.

## For AI agents

Search, browse, create, update, and delete catalog items in a CollectiveAccess Providence collection through 8 table-aware endpoints, including media-representation lookups.

## Scope

Does not handle e-commerce, ticketing, or end-user accounts - use for collection cataloging, search, and media metadata only.

## Capabilities

- Search any catalog table with structured criteria via GET `/find/{table}`
- Browse a table by facet or hierarchy via GET `/browse/{table}`
- Retrieve a single item with all attributes via GET `/item/{table}/id/{item_id}`
- Create a new catalog record via PUT `/item/{table}`
- Update or delete an existing record via PUT or DELETE `/item/{table}/id/{item_id}`
- List media representations attached to an item via `/item/{table}/id/{item_id}/media/{representation_id}/representations`
- Introspect a table's data model via GET `/model/{table}`

## Use cases

### Programmatic Collection Cataloging

Bulk-import catalog records into a CollectiveAccess Providence instance by calling PUT `/item/{table}` for each new accession. Tables are vendor-defined (objects, entities, occurrences, places) and the same endpoint handles any of them; the table name is a path parameter. This pattern fits museum digitisation projects that need to seed a fresh collection from a spreadsheet or external CMS.

Example prompt: For each row in a spreadsheet, call PUT `/item/objects` with the parsed metadata payload to create the accession record

### Public Search Front-End

Expose a public collection search by proxying GET `/find/{table}` from a custom front-end. CollectiveAccess returns structured results with attributes ready to render in a card list. A library or archive can build a custom Vue or React UI on top of Providence without exposing the back-office UI.

Example prompt: Call GET `/find/objects` with a query parameter for the user's keyword, then render the returned items in a search results page

### Asset Reconciliation

Reconcile a digital asset library with the catalog by listing media representations on each object via `/item/{table}/id/{item_id}/media/{representation_id}/representations.` An audit script can flag objects with missing or duplicate representations so curators can correct them. This supports preservation workflows that require complete media coverage.

Example prompt: For each catalog object, call GET `/item/objects/id/{item_id}/media/{representation_id}/representations` and report any object with zero attached media

### AI Agent Cataloging via Jentic

Drive cataloging from an LLM by searching Jentic for the operation needed (find items, create record, update description) and executing it. CollectiveAccess Basic credentials live in your Jentic One instance and are injected at execution so the agent never sees the username and password. Useful for AI-assisted metadata enrichment and triage.

Example prompt: Use Jentic to search 'create a catalog item', load the PUT `/item/{table}` schema, and execute it with the generated metadata for the objects table

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| PUT | `/item/{table}` | Create a new catalog item |
| PUT | `/item/{table}/id/{item_id}` | Update a catalog item |
| DELETE | `/item/{table}/id/{item_id}` | Delete a catalog item |
| GET | `/item/{table}/id/{item_id}` | Get a catalog item by ID |
| GET | `/find/{table}` | Search items in a table |
| GET | `/browse/{table}` | Browse items in a table |
| GET | `/model/{table}` | Get a table's data model |

## Key resources

- **Items** — Records in any cataloging table - objects, entities, occurrences, places, collections
- **Find** — Structured search across a table
- **Browse** — Faceted and hierarchical browse over a table
- **Media Representations** — Digital files attached to a catalog item
- **Model** — Data-model metadata for a table

## Why Jentic

- **Setup:** Wiring CollectiveAccess by hand means setting HTTP Basic auth against your own Providence server URL that fills the service.php base and handling the item, find, and browse endpoints yourself. Through Jentic you install once, import CollectiveAccess from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** CollectiveAccess addresses records through the request path and body, so you scope by operations: limit the agent to the calls it needs, such as finding or reading a catalog item, so write actions like editing or deleting an item are not included unless you add them.
- **Credential handling:** Your CollectiveAccess Basic auth credentials are stored once, encrypted, by your own Jentic One instance and injected into the Authorization header at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a catalog item' or 'search the collection', and Jentic returns the matching CollectiveAccess operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Airtable API** — Hosted relational database popular for lightweight collection cataloging
- **Contentful API** — Headless CMS with structured content models
- **Notion API** — Lightweight knowledge base for staff documentation alongside the formal catalog

## FAQ

### What authentication does the CollectiveAccess API use?

The API uses HTTP Basic authentication with the credentials of a CollectiveAccess Providence user. Through Jentic the username and password are stored encrypted in the vault and injected at execution so they never enter the agent's prompt.

### Which tables can I query with the CollectiveAccess API?

All cataloging tables defined in your Providence installation are addressable through the {table} path parameter - objects, entities, occurrences, places, collections, and any custom tables. Use GET `/model/{table}` to introspect a table's fields before constructing queries.

### Can I attach media files via the CollectiveAccess API?

Media representations attached to an item are listed via GET `/item/{table}/id/{item_id}/media/{representation_id}/representations.` The OpenAPI surface focuses on metadata CRUD and read access to existing media; uploading new media files is typically done through the Providence back-office.

### Is CollectiveAccess hosted or self-hosted?

CollectiveAccess Providence is self-hosted. The base URL is {server_url}/service.php where {server_url} is your own Providence installation. There is no public multi-tenant endpoint - every deployment is independent.

### What are the rate limits for the CollectiveAccess API?

Because each Providence install is self-hosted there are no central rate limits; throughput is bounded only by your server resources. Add caching in front of GET `/find/{table}` for high-traffic public search front-ends.

### How do I create a catalog item with the CollectiveAccess API through Jentic?

Search Jentic for 'create a catalog item', load the PUT `/item/{table}` schema, and execute it with the table name (e.g. objects) and the metadata payload. Jentic injects the Basic auth header from the vault.

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

Yes. Because Jentic One is self-hosted, you set the rules that decide which CollectiveAccess operations and credentials your agent may use. Since the API addresses records through the request path and body, you scope by operation: grant the agent only the calls it needs, such as GET `/find/{table}` and GET `/item/{table}/id/{item_id}` to search and read catalog items. Write actions like PUT `/item/{table}` and DELETE `/item/{table}/id/{item_id}` stay out of reach unless you explicitly allow them.