API Reference

The sarvaFeed REST API lets you programmatically manage resources, automate workflows, and build custom integrations.

Overview

The sarvaFeed API follows REST conventions and returns JSON responses for all endpoints. The base URL for API requests is your instance URL followed by /api/v1. All requests must be made over HTTPS in production environments.

Responses use standard HTTP status codes. 2xx codes indicate success, 4xx codes indicate client errors (invalid parameters, authentication failures), and 5xx codes indicate server errors.

All list endpoints support pagination through page and per_page query parameters. The default page size is 25 items, with a maximum of 100.

Authentication

All API requests require authentication via a bearer token. Generate an API token from the sarvaFeed dashboard under Settings → API Tokens. Include the token in the Authorization header of every request.

Authorization: Bearer your-api-token-here

Tokens inherit the permissions of the user who created them. For automated systems and CI/CD pipelines, we recommend creating a dedicated service account with only the permissions your integration requires.

Requests without a valid token receive a 401 Unauthorized response. Tokens do not expire by default but can be revoked at any time from the dashboard.

Endpoints

The API exposes CRUD operations for all core resources. Below is a summary of the available endpoint groups. Full request and response schemas are documented in the interactive API explorer bundled with every sarvaFeed instance.

GET/api/v1/resources

List all resources with optional filtering and pagination.

POST/api/v1/resources

Create a new resource. Accepts a JSON body with required fields.

GET/api/v1/resources/:id

Retrieve a single resource by its unique identifier.

PATCH/api/v1/resources/:id

Update specific fields on an existing resource.

DELETE/api/v1/resources/:id

Permanently delete a resource. This action cannot be undone.

Rate Limiting

To protect the stability of your instance, the API enforces rate limits on all endpoints. The default limit is 100 requests per minute per API token. If you exceed this limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating when you can resume.

Rate limit headers are included in every response so your client can track remaining quota: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

Self-hosted administrators can adjust rate limits through the RATE_LIMIT_PER_MINUTE environment variable. Set it to 0 to disable rate limiting entirely on trusted internal networks.

Examples

Below is a basic example using curl to list resources from your sarvaFeed instance:

curl -H "Authorization: Bearer your-token" \
  https://your-instance.example.com/api/v1/resources

To create a new resource, send a POST request with a JSON body:

curl -X POST \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{"name": "Example", "description": "A new resource"}' \
  https://your-instance.example.com/api/v1/resources

For more examples and language-specific SDKs, visit the GitHub repository.