Flexible input
Send a raw sentence, a partially complete object, document text, a URL or a group of records. Preserve the original input for traceability.
API architecture and endpoints
A Practical Enrich API for Structured AI Data
The Enrich API creates a clear boundary between raw application data and validated, AI-generated context. Define the fields you need, run a controlled pipeline and return predictable JSON.
REST interfaceBearer keysIdempotencyWebhooks
Core concept
One request contract for many enrichment tasks
A stable API contract keeps provider-specific prompt logic out of product code and gives teams one place to govern output quality.
Explicit operations
Name every requested enrichment. A field can be extracted, classified, summarized, normalized, scored or resolved.
Typed output
Return a schema-bound object with validation status, confidence metadata, provider trace and actionable errors.
Request lifecycle
How an Enrich API request moves through the system
Each stage has a narrow responsibility. That makes failures easier to diagnose and quality easier to measure.
Authenticate
Validate a scoped API key and attach account-level limits.
Normalize
Clean encoding, map aliases and identify the record type.
Plan
Resolve enrichments, schemas and provider routing policy.
Execute
Run extraction, model calls, tools and deterministic transforms.
Validate
Check the output and return data, warnings or an error object.
API surface
A small endpoint set with clear responsibilities
These static examples describe an intended interface. They do not create a live service until you connect a backend.
| Method | Endpoint | Purpose | Typical response |
|---|---|---|---|
| POST | /v1/enrich | Run a synchronous enrichment for one record. | Validated data object and execution metadata. |
| POST | /v1/enrich/batch | Create an asynchronous job for many records. | Job identifier, accepted count and status URL. |
| GET | /v1/jobs/{job_id} | Read batch progress and retrieve completed output. | Queued, running, completed or failed job state. |
| GET | /v1/schemas | List available output schemas and versions. | Schema names, versions and compatibility details. |
| POST | /v1/validate | Validate an object without rerunning enrichment. | Field-level validation results and repair hints. |
Request and response
Make the input, intent and output contract visible
A readable request helps developers understand what the pipeline will do. A stable response makes integration predictable.
POST /v1/enrich HTTP/1.1
Host: api.enrichapi.com
Authorization: Bearer $ENRICH_API_KEY
Content-Type: application/json
Idempotency-Key: 9f42c7f7-example
{
"input": {
"company": "Example Robotics",
"website": "example.com"
},
"enrichments": [
"company_summary",
"industry",
"location",
"semantic_tags"
],
"schema": "company_profile_v1",
"routing": {
"policy": "balanced",
"fallback": true
}
}{
"request_id": "req_01JEXAMPLE",
"status": "completed",
"data": {
"company_name": "Example Robotics",
"industry": "Industrial automation",
"summary": "Software for warehouse robotics and fleet operations.",
"location": {
"city": "San Francisco",
"country": "United States"
},
"semantic_tags": ["robotics", "warehouse-ai", "fleet-operations"]
},
"validation": {
"schema": "company_profile_v1",
"valid": true,
"warnings": []
}
}Reliability controls
Design the Enrich API for retries, limits and observability
AI enrichment becomes operationally useful when every request is traceable and safe to retry.
Idempotency keys
Prevent duplicate work when a client retries after a timeout or interrupted connection.
Rate-limit headers
Expose remaining quota, reset timing and request cost so clients can back off gracefully.
Request tracing
Return a request identifier and preserve stage-level timing without logging sensitive content by default.
Stable error codes
Separate authentication, input validation, provider failure, schema failure and quota errors.
Signed webhooks
Verify batch completion events with timestamps, replay protection and rotating secrets.
Versioned schemas
Allow additive changes while protecting clients from unexpected field or type changes.
Enrich API FAQ
Questions developers ask before integration
Use these answers as an implementation checklist before connecting the static interface to a backend.
What input formats can the Enrich API accept?
The interface is designed around JSON requests that can contain text, key-value records, URLs, document text or arrays of records. Binary uploads would require a production backend and upload policy.
How does authentication work?
The documentation uses bearer API keys in the Authorization header. Production deployments should create scoped keys, rotate secrets, store hashes rather than plaintext and never expose server keys in browser code.
Can one request ask for several enrichments?
Yes. A request can list several enrichment operations, such as classification, entity extraction, summarization and tagging. Each operation should map to a defined output field or nested object.
How should errors be returned?
Use stable HTTP status codes plus a machine-readable error object with a code, message, request identifier and retry guidance. Validation errors should identify the exact field that failed.
Does the API support batch jobs?
The architecture includes synchronous single-record requests and asynchronous batch-job patterns. Large jobs should use idempotency keys, job status endpoints and webhooks.
Define your first enrichment request
Start with one record type, one schema and a small set of fields. Then expand the pipeline after you can measure quality and failure modes.