API

API overview

The Cension API allows you to programmatically manage your datasets and workflows.

Horizontal vs vertical

Understanding the two primary modes of dataset creation.

Cension distinguishes between two primary types of data operations:

Vertical operations (discovery & growth)

"Find new rows."

Vertical operations are about growing your dataset by discovering new items. You provide a context (what you are looking for), and Cension discovers and adds new items (rows) to your dataset.

Example: "Find 1,000 SaaS companies that operate in the Healthcare sector."
Result: Adds new rows to your dataset.
Endpoint: POST /api/vertical/create

1{
2  "feedId": 123,
3  "projectId": 456,
4  "fieldContextId": 789,
5  "count": 50
6}

Horizontal operations (enrichment)

"Fill in the columns."

Horizontal operations are about enriching existing items. You provide a list of items (IDs) and a list of fields (columns) you want to populate, and Cension processes those specific cells.

Example: "For these 500 companies, find their 'CEO Name' and 'LinkedIn URL'."
Result: Updates specific columns for existing rows.
Endpoint: POST /api/horizontal/create

1{
2  "feedId": 123,
3  "projectId": 456,
4  "ogIds": ["item_1", "item_2", "item_3"],
5  "fieldIds": [10, 11, 12],
6  "processingMode": "FillEmpty"
7}

Authentication

Secure your API requests with API keys.

Authentication is performed using a Universal API Key. This single key authenticates you for all operations (Datasets, Saved Queries, Exports). You can generate and manage your API keys in the Cension application under Settings → API Keys. All API requests must include your API Key in the Authorization header.

1Authorization: <your_api_key>

Your API key will typically start with the prefix cension_.

Response format

Standard JSON response structure.

The API returns responses in JSON format. Standard responses include a success status and a data payload or message.

Success response example

1{
2  "success": true,
3  "data": { ... }
4}

Error response example

1{
2  "success": false,
3  "message": "Invalid API Key",
4  "error_code": "UNAUTHORIZED"
5}

Pagination

Handling large lists of data.

List endpoints (like GET /api/queries/{savedQueryId}) return a pagination object in the response:

1{
2  "success": true,
3  "data": [ ... ],
4  "pagination": {
5    "page": 1,
6    "limit": 100,
7    "total_count": 1450,
8    "total_pages": 15
9  }
10}

Error codes

Common error codes and meanings.

Error code	HTTP status	Description
UNAUTHORIZED	401	Invalid or missing API key.
FORBIDDEN	403	You do not have permission to access this resource.
NOT_FOUND	404	The requested resource (feed, project, query) does not exist.
INTERNAL_ERROR	500	An unexpected error occurred on the server.

Rate limits

Understand the limits on API usage to ensure stability.

Request limits

Max records per request: 10,000 items (e.g., when uploading data or requesting horizontal processing).
Max concurrent operations: 10 active operations per user.
Max request body size: 50 MB.
Operation timeout: Long-running operations are processed asynchronously. The initial request timeout is set to 2 minutes, but the background operation can run for up to 24 hours.

Rate limiting

While we do not publish hard per-second rate limits, we employ a dynamic rate-limiting system based on your plan and server load.

Standard expectation: ~1-10 requests per second burst capacity is typical.
Fair usage: If you receive a 429 Too Many Requests response, please pause your integration and retry with an exponential backoff strategy.

Best practice

Tips for efficient and effective API integration.

1. Batch your requests

Avoid making single requests for individual items. Instead of sending 1,000 requests for 1 item each, send 1 request with 1,000 items. This significantly improves throughput and reduces the chance of hitting rate limits.

2. Handle asynchronous operations

Data processing (both Vertical and Horizontal) takes time. The API will return an operationId immediately.

Endpoint: GET /api/operations/feed/{feedId}/all
Procedure:
1. Start an operation (e.g., via /api/horizontal/create).
2. Store the operationId returned.
3. Active monitoring: Poll GET /api/operations/feed/{feedId}/active while the operation is running.
4. Completion: Once the operation disappears from the "active" endpoint (or returns 404), query GET /api/operations/feed/{feedId}/all to verify its final status.

3. Error handling

Always check the success boolean in the response. If false, investigate the message and error_code.

UNAUTHORIZED: Check your API key.
NOT_FOUND: Check your feed_id, project_id, or savedQueryId.
INTERNAL_ERROR: Retry the request. If it persists, contact support.

4. Use saved queries

For complex data retrieval, it is best practice to write and test your SQL query in the Cension UI, save it, and then execute it via the API using its ID. This ensures your data retrieval logic is consistent and easily managed without changing your code.