Making requests

Every API on APIHiver is called through the gateway. You don't need anything installed: any HTTP client works, including cURL, fetch, Python requests, Postman and so on.

The gateway address

Each API has its own secure address:

Add the endpoint's path to it. For example, the Weather API's /v1/current endpoint is:

The exact address, path and parameters for every endpoint are shown on its page and in the code snippets. Always use https://.

Authentication

Send your API key in the X-API-Key header on every request:

curl "https://weather.p.apihiver.com/v1/current?city=Mumbai" \
  -H "X-API-Key: YOUR_API_KEY"

The gateway removes this header before forwarding the request, so the provider never sees your key.

Query and path parameters

• Query parameters go after ? in the URL: /v1/rates?base=USD&symbols=INR,EUR. Remember to URL-encode values that contain spaces or special characters.
• Path parameters are part of the path itself. On an endpoint documented as /v1/ifsc/{code}, you call /v1/ifsc/SBIN0000300.

JSON request bodies

For POST endpoints that take JSON, send the body with a Content-Type: application/json header:

curl -X POST "https://text-analysis.p.apihiver.com/v1/sentiment" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "I love this product!"}'

Uploading files

Endpoints that process files (images, video, documents) usually accept multipart/form-data, with the file in a field named on the endpoint's page (often file):

curl -X POST "https://ocr-image-to-text.p.apihiver.com/v1/extract" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F file=@receipt.jpg

Many also accept JSON with a public url or a base64 string instead of a file. Check the endpoint's body description. Each API sets its own maximum upload size, shown on the endpoint's page.

Responses

A successful call returns the provider's response unchanged, usually 200 OK with JSON. Some endpoints return images, audio or CSV; save the body to a file (-o output.png in cURL).

Every response also carries headers from the gateway: a unique X-Request-Id (quote it when asking for help) and your remaining rate limit and quota. See Headers.

When something goes wrong

Errors are JSON: {"error": {"code": "...", "message": "..."}}. Errors produced by the gateway (a missing key, no subscription, rate limited) are listed in Error codes. Errors produced by the API itself (a missing parameter, nothing found) are described on each endpoint's page.

Timeouts

Each API has a maximum response time, set by the provider. Most answer in well under a second; APIs that process video or large files can take longer. If the provider's server doesn't answer in time, you get 502 BAD_GATEWAY and can safely retry.