canonical: https://jentic.com/apis/apigee.local/apigee-registry

# Apigee Registry API

The Apigee Registry API is a Google-managed service for cataloguing and versioning API descriptions inside an organization. It models APIs, deployments, and revisions as first-class resources under `/v1/projects/{project}/locations/{location}/apis`, so teams can attach OpenAPI documents, GraphQL schemas, and Protobuf definitions to a stable identity over time. The Registry exposes 35 endpoints for CRUD on APIs and deployments, listing and tagging revisions, and rolling back to earlier versions. It is typically used to build internal API catalogs and to track which spec is live in each environment.

## For AI agents

Catalogue, version, and tag internal API descriptions across an organization through 35 endpoints covering APIs, deployments, and revisions.

## Scope

Does not handle traffic routing, request transformation, or runtime API gateway policies - use for cataloguing and versioning API descriptions only.

## Capabilities

- Register a new API entry under a project and location with display name, description, and owner metadata
- Create deployments that bind a specific spec revision to an environment such as staging or production
- List, tag, and roll back revisions of an API deployment to recover a known-good description
- Patch API and deployment metadata in place without disturbing the underlying revision history
- Delete deprecated APIs or specific deployment revisions while preserving the parent resource
- Browse the registry hierarchically through nested /apis, /deployments, and /:listRevisions calls

## Use cases

### Internal API catalog of record

Use the Registry as the single source of truth for which APIs exist inside an organization, who owns them, and where they are deployed. Teams register each API once with POST `/v1/projects/{project}/locations/{location}/apis`, then attach revisions and deployments as the spec evolves. Engineering portals and governance tooling read `/v1/.../apis` and `/v1/.../deployments` to render an accurate, machine-generated catalog instead of a hand-edited wiki.

Example prompt: POST `/v1/projects/acme/locations/global/apis` with apiId=payments and a body containing displayName and description, then list `/v1/projects/acme/locations/global/apis` to confirm.

### Spec versioning with rollback

Track every change to an API description as a revision, then promote or roll back specific revisions per environment. The Registry's :listRevisions and :deleteRevision actions on a deployment let CI/CD systems publish a new revision on each merge and a rollback workflow can re-tag an earlier revision without rebuilding artefacts. This protects consumers from breaking changes and gives auditors a complete history of contract changes.

Example prompt: GET `/v1/projects/acme/locations/global/apis/payments/deployments/prod`:listRevisions, pick a revision, then PATCH the deployment to point at it.

### Governance and compliance reporting

Compliance teams query the Registry to prove which API contracts are in production, who owns them, and when they last changed. Because every API and deployment carries createTime, updateTime, and labels, simple reads of `/v1/.../apis` and `/v1/.../deployments` give auditors the evidence they need without polling individual gateways. New APIs that bypass the catalog are easy to spot when the registry is the gating control.

Example prompt: List all APIs and deployments under `/v1/projects/acme/locations/global/apis` and join updateTime with labels.owner to produce an ownership report.

### Agent-driven catalog maintenance

An AI agent that watches pull requests can register new APIs and create new deployment revisions automatically when a spec file lands on main. Through Jentic the agent calls Registry_CreateApi and Registry_CreateApiDeployment without holding Google credentials directly, and the registry stays in step with the codebase with no human curation. This converts the catalog from a wiki to a continuously generated artefact.

Example prompt: Through Jentic, search 'register an internal API', load Registry_CreateApi, then call it with apiId and metadata derived from the merged spec file.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v1/projects/{project}/locations/{location}/apis` | List APIs in a project and location |
| POST | `/v1/projects/{project}/locations/{location}/apis` | Create a new API entry |
| PATCH | `/v1/projects/{project}/locations/{location}/apis/{api}` | Update API metadata |
| GET | `/v1/projects/{project}/locations/{location}/apis/{api}/deployments` | List deployments for an API |
| POST | `/v1/projects/{project}/locations/{location}/apis/{api}/deployments` | Create a deployment revision |
| GET | `/v1/projects/{project}/locations/{location}/apis/{api}/deployments/{deployment}:listRevisions` | List revisions of a deployment |

## Key resources

- **Apis** — Top-level API entries under `/v1/projects/{project}/locations/{location}/apis.`
- **ApiDeployments** — Bindings of an API to an environment under `/v1/.../apis/{api}/deployments.`
- **Revisions** — Immutable history of deployment changes accessible via :listRevisions and :deleteRevision.

## Why Jentic

- **Setup:** Wiring the Apigee Registry API by hand means setting up Google auth, learning the project, location, and API resource shapes, and managing deployments and revisions yourself. Through Jentic you install once, import Apigee Registry from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** The Apigee Registry API puts the API id in the URL path (`/projects/{project}/locations/{location}/apis/{api}/...`), so a rule can pin your agent to one API entry: it can read and update that api's deployments and nothing else. You choose the operations it may call, so creating new apis is not included unless you add it.
- **Credential handling:** Your Apigee Registry credential 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 'list registered APIs' or 'read an API's deployments', and Jentic returns the matching Apigee Registry operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **SwaggerHub API** — SmartBear's hosted API design and registry product.
- **Stoplight** — Spec-first API design and documentation hub.
- **GitHub API** — Source of truth for spec files often pushed into the Registry.

## FAQ

### What authentication does the Apigee Registry API use?

The OpenAPI spec does not declare a securityScheme, but the Registry runs on apigeeregistry.googleapis.com and inherits Google Cloud authentication, which means OAuth 2.0 or service-account credentials in production. When called through Jentic, those Google credentials are stored in your Jentic One instance and never reach the agent.

### Can I version API specs and roll back to a previous revision?

Yes. Each ApiDeployment under `/v1/projects/{project}/locations/{location}/apis/{api}/deployments` tracks revisions. Call GET .../{deployment}:listRevisions to see history, then PATCH the deployment to point at an earlier revision or DELETE .../{deployment}:deleteRevision to remove a specific one.

### How do I register a new API through Jentic?

Search Jentic for 'register an internal API', load the Registry_CreateApi operation, and execute with the parent `/v1/projects/{project}/locations/{location}`, an apiId, and a body containing displayName and description. The new entry is immediately listable via Registry_ListApis.

### What are the rate limits for the Apigee Registry API?

The OpenAPI spec does not declare specific limits. Apigee Registry runs on Google Cloud and is subject to per-project quotas configurable in the Google Cloud Console. Watch for HTTP 429 and apply exponential backoff.

### Does the Registry support managing API deployments per environment?

Yes. The `/v1/projects/{project}/locations/{location}/apis/{api}/deployments` collection lets you create distinct deployment resources, typically one per environment. Each deployment has its own revision history so staging and production can move independently.

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

Yes. Because you self-host Jentic One, your own rules decide which Apigee Registry operations and credentials your agent may use. The API id lives in the URL path (`/projects/{project}/locations/{location}/apis/{api}/...`), so a rule can pin the agent to a single API entry and let it list, read, and update just that api's deployments and revisions. You pick the exact operations it may call, so creating new APIs stays out of scope unless you explicitly allow it.