canonical: https://jentic.com/apis/coreo.io/coreo

# Coreo API

The Coreo API reads ecological survey data from projects on the Coreo platform, returning the surveys defined for a project and the records collected against them. It also exposes the UKHab habitat module, with baselines, pre-surveys, and species feature notes for a project. Responses are lean by default, returning related objects as IDs, and an expand query parameter pulls in related objects such as user, survey, and geometry in a single request. API keys are read-only and must have access to the requested project.

## For AI agents

Read ecological project data from Coreo: a project's surveys and the records collected against them, plus UKHab baselines, pre-surveys, and species feature notes. Read-only.

## Scope

Does not create surveys, write records, or render maps. Use for reading ecological project survey data, records, and UKHab modules only.

## Capabilities

- List the surveys defined for a project
- List and read the records collected against a project's surveys
- Read UKHab baselines for a project
- Read UKHab pre-surveys for a project
- Read UKHab species feature notes for a project
- Expand related objects such as user, survey, and geometry in one request

## Use cases

### Agent survey-data retrieval

An AI agent connected through Jentic lists a project's surveys and pulls the records collected against them to answer a question about field observations, without a human exporting data from Coreo. Because the agent uses a read-only key, it can read project data but cannot change it.

Example prompt: List the surveys for a project and retrieve the records for the chosen survey, expanding the survey and geometry

### UKHab habitat reporting

Ecology consultants read a project's UKHab baselines, pre-surveys, and species feature notes to assemble a habitat report. Coreo exposes each UKHab record type as its own endpoint so an agent can gather baselines and species feature notes for one project in sequence.

Example prompt: Read the UKHab baselines and species feature notes for a project and compile them into a single summary

### Lean-to-expanded data sync

A data pipeline first reads records in Coreo's lean form, where related objects are returned as IDs, then re-requests with the expand parameter to hydrate user, survey, and geometry only where needed. This keeps routine syncs small while still allowing full detail on demand.

Example prompt: Fetch a project's records in lean form, then re-fetch a single record with expand set to user, survey, and geometry

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v1/projects/{projectId}/surveys` | List project surveys |
| GET | `/v1/projects/{projectId}/records` | List project records |
| GET | `/v1/projects/{projectId}/records/{recordId}` | Get a single record |
| GET | `/v1/modules/ukhab/projects/{projectId}/baselines` | List UKHab baselines |
| GET | `/v1/modules/ukhab/projects/{projectId}/presurveys` | List UKHab pre-surveys |
| GET | `/v1/modules/ukhab/projects/{projectId}/sfns` | List UKHab species feature notes |

## Key resources

- **Surveys** — List the surveys defined for a project
- **Records** — List and read the records collected against a project's surveys
- **UKHab baselines** — Read UKHab baselines for a project
- **UKHab pre-surveys** — Read UKHab pre-surveys for a project
- **UKHab species feature notes** — Read UKHab species feature notes for a project

## 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:** 46 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 59 / 100
  - Developer Experience & Jentic Compatibility: 63 / 100
  - AI-Readiness & Agent Experience: 24 / 100
  - Agent Usability: 94 / 100
  - Security: 50 / 100
  - AI Discoverability: 74 / 100
- **View full report:** https://jentic.com/apis/coreo.io/coreo/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 Coreo API by hand means issuing a read-only JWT, sending it in the Authorization header with the literal JWT prefix, and learning the expand query parameter for lean responses. Through Jentic you install once, import Coreo from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Coreo puts the projectId in the URL path (`/v1/projects/{projectId}/...`) and its keys are read-only, so a rule can pin your agent to one project. You choose the read operations it may call, so it can read that project's surveys and records and nothing on other projects unless you add them.
- **Credential handling:** Your Coreo token 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 'read project records' or 'read UKHab baselines', and Jentic returns the matching Coreo operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **123FormBuilder** — 123FormBuilder builds forms and collects their responses, where Coreo reads ecological survey records.
- **CViewSurvey** — CViewSurvey captures field survey data on mobile devices.
- **AidaForm** — AidaForm collects form and survey responses that can feed a wider data workflow.

## FAQ

### What authentication does the Coreo API use?

The Coreo API authenticates with a token sent in the Authorization header, prefixed with the literal word JWT and a space, per its OpenAPI spec. API keys are read-only and must have access to the requested project. Through Jentic the token is stored once by your own self-hosted instance and injected when a call runs, so it never appears in the agent's prompt or logs.

### Can I read a project's records with the Coreo API?

Yes. List the surveys for a project, then read the records collected against them, or get a single record by its id. Responses are lean by default and return related objects as IDs, so pass the expand parameter to hydrate user, survey, and geometry when you need the full objects.

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

Yes. The API is read-only and Coreo puts the projectId in the URL path, so a rule can pin your agent to one project and the survey and record read operations you choose, so it cannot read other projects, and every call it makes is logged.

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

The spec states that requests are limited per IP and per authenticated user, and that an exceeded limit returns a 429 response with a Retry-After header. Check the Coreo documentation for the current numeric limits before running large syncs.

### Is there a Coreo MCP server?

You don't need an MCP server to give your agent the Coreo API. Jentic connects it directly from the API Directory: import it, store your token once, and your agent calls the survey and record read operations on demand without loading another server's tool definitions into its context.

### How do I read survey records with the Coreo API through Jentic?

Search Jentic by intent such as 'read project survey records', and Jentic returns the records operation with its input schema so your agent passes the projectId and reads back the records. To run it on your own infrastructure, install Jentic One from its GitHub repo.