Go
Hosted tools
A list of tools. Call the API, get the response. Long operations return jobs.
What hosted tools are#
Hosted tools are a list of tools: call the API and get the response. Use ordinary HTTP requests with your Haider API key. Discovery is free for every valid key. Execution requires active Go or Go Max.
| Request | Purpose |
|---|---|
GET /v1/tools/categories | Browse categories |
GET /v1/tools?category= | List tools in a category |
GET /v1/tools/search | Search tool names, tags and summaries |
GET /v1/tools/{id} | Read one tool's schema, price and limits |
POST /v1/tools/{id}/invoke | Call it with Idempotency-Key and max_credits |
Long operations return 202 and a job ID. Follow status, SSE events and results, or request cancellation. Outputs are private; use Artifacts to publish HTML separately.
Hosted tools are launching in stages. Missing upstream keys show needs_key. Staged tools stay coming until the operator completes their rollout; a key or admin switch cannot bypass that stage. BYOK social scraping remains dormant. No release dates are promised.
Discover a tool#
Start with categories, list or search, then describe the selected ID. Replace <HK_KEY> with your hk- key. Send exactly one Authorization header; a browser session alone does not authenticate the API.
curl 'https://haidercode.ai/v1/tools/categories' \ -H 'Authorization: Bearer <HK_KEY>' curl 'https://haidercode.ai/v1/tools?category=data&fields=id,availability' \ -H 'Authorization: Bearer <HK_KEY>' curl 'https://haidercode.ai/v1/tools/search?q=web%20research&fields=id,title' \ -H 'Authorization: Bearer <HK_KEY>' curl 'https://haidercode.ai/v1/tools/search.web' \ -H 'Authorization: Bearer <HK_KEY>' curl 'https://haidercode.ai/v1/tools/data.dns' \ -H 'Authorization: Bearer <HK_KEY>'
These requests reproduce the recorded discovery examples. Search looks through catalog metadata; it does not search the web upstream. Lists return {tools:[...],next_cursor:null|string}. Copy a non-null cursor unchanged and preserve the query, category and projection for the next page.
Describe supplies input_schema, version, availability, price, default result fields and limits. Check it before invoking. Discovery performs no charging. The public catalog also shows the current rollout.
Invoke and retry#
This DNS request matches the offline invocation recording's inputs and idempotency key. One credit equals $1; max_credits caps total usage, including allowance-funded usage. The ceiling must cover the tool's maximum quote. DNS costs 0.01 credit per call.
curl -X POST 'https://haidercode.ai/v1/tools/data.dns/invoke' \
-H 'Authorization: Bearer <HK_KEY>' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: canonical' \
-d '{"arguments":{"name":"example.com","type":"A"},"max_credits":"0.03"}'
The recorded response is below. Its address, TTL and job placeholder are synthetic fixture data; live answers differ.
{"data":[{"data":"192.0.2.1","name":"example.com","ttl":60,"type":"A"}],"job_id":"<job_id>","next_cursor":null,"receipt":{"allowance_cents":1,"credits_cents":0,"price_version":"1","units":1,"upstream_cost_cents":0},"status":"complete","warnings":[]}
Use a distinct idempotency key for each intended operation. For retries of that operation, keep the same key, arguments, version, spending ceiling and result projection. Replays return the original response for 24 hours without another dispatch or charge. Changing bound facts returns 409 idempotency.
A replayed 202 stays 202 even after completion: read the job. A recorded 402 stays 402 after funding; deliberately retry with a new key only when you intend a new attempt. An uncertain response is never a reason to create a replacement operation automatically.
Jobs and private results#
The HTTP request waits up to the tool's synchronous deadline, at most 15 seconds. Work that continues returns 202 {"job_id":"tj_...","status":"running"}; use the returned status as authoritative. Jobs have at most ten minutes to finish.
| Request | Result |
|---|---|
GET /v1/tools/jobs/{id} | Status, cancellation intent and settlement receipt |
GET /v1/tools/jobs/{id}/events | SSE status events; resume with Last-Event-ID |
GET /v1/tools/jobs/{id}/results?cursor=... | Complete or partial data, receipt and next cursor |
POST /v1/tools/jobs/{id}/cancel | Idempotent cancellation intent |
Each curl below is a shape from the contract. Replace <JOB_ID> with the ID returned by your invocation.
curl -N 'https://haidercode.ai/v1/tools/jobs/<JOB_ID>/events' \ -H 'Authorization: Bearer <HK_KEY>' \ -H 'Last-Event-ID: 0' curl 'https://haidercode.ai/v1/tools/jobs/<JOB_ID>/results' \ -H 'Authorization: Bearer <HK_KEY>' curl -X POST 'https://haidercode.ai/v1/tools/jobs/<JOB_ID>/cancel' \ -H 'Authorization: Bearer <HK_KEY>'
Only the original caller, still billed to the same owner, can read or cancel a job. Results expire 24 hours after completion. Cancellation is cooperative and may leave completed usage to pay. reconciling means the outcome is uncertain and funds remain reserved pending recovery; do not invoke again to poll.
Funding and the weekly window#
Go's weekly allowance covers hosted models and tools; usage-credits top it up. A tool reserves its retail price from the same plan window used by models, then from usage-credits, then returns 402 if it cannot be funded after any permitted auto-topup. Credits alone do not unlock tools without active Go or Go Max.
GET /v1/account returns one weekly_allowance window. Its percent_remaining includes settled model and tool usage and pending allowance holds. Show one ratio and the usage_credits_usd balance, which already excludes credit holds. The example is illustrative.
Weekly allowance [###############.....] 75% remaining This week: models 15%, tools 5%, pending 5% of the allowance Usage-credits $2.34 available
weekly_allowance.resets_at_ms is the weekly reset in Unix milliseconds. tools_access reports admission. Settlement uses allowance first, up to the whole allowance hold plus any unheld allowance still free in the same current weekly window; usage-credits cover only the remainder. It returns a receipt with allowance_cents and credits_cents and releases unused holds to their original week and credits balance.
For example, reserving 150 cents as 100 allowance + 50 credits and completing 90 cents charges 90 allowance + 0 credits, releasing 10 allowance + 50 credits. Proportional settlement applies only to legacy holds recorded before this release against the old tools allowance bucket. A member's usage bills their owner. Read Billing for credit topups.
Custom tools#
Custom tools are not available yet.
Connections and posting#
X and LinkedIn posting require both operator-configured OAuth app credentials and the caller's own active social connection. A platform key or team membership grants no posting authority.
This curl is a shape from the contract for starting an X connection.
curl -X POST 'https://haidercode.ai/v1/connections' \
-H 'Authorization: Bearer <HK_KEY>' \
-H 'Content-Type: application/json' \
-d '{"provider":"x"}'
Open the returned authorization_url and complete authorization while signed in as the initiating user. Use linkedin for LinkedIn. List your connections with GET /v1/connections and revoke one with DELETE /v1/connections/{id}.
Describe social.x.post or social.linkedin.post, then invoke with your connection ID, post text and explicit confirm:true in arguments, plus the normal idempotency key and spending ceiling. Missing confirmation returns 400 invalid. Missing authorization returns 409 tool_unavailable with reason connection_required; an unusable authorization returns 409 connection. Reconnect before deliberately trying again.
Availability and rollout#
| State | Meaning |
|---|---|
available (Live) | Configuration prerequisites are present; account, adapter and user authorization checks still apply |
needs_key (Waiting on a key) | The operator must configure the required upstream credential |
coming (Coming) | Staged for a later rollout; a key or switch cannot bypass it |
disabled (Off) | The administrator disabled this tool |
byok (Your key) | A private caller credential is required; social scraping activation remains dormant |
See the public catalog for the live rollout.
Visible unavailable tools return 409 tool_unavailable. Refresh discovery after an operator change. Saving an Apify token and enabling a switch do not activate the dormant scrapers: their shipped actor build pins remain unconfigured.
BYOK#
BYOK means bring your own upstream key. Apify social scraping is dormant: a stored credential and an administrator switch are not enough to run an actor. The operator must also approve an immutable actor build pin and execution bounds.
There is no dashboard BYOK credential editor yet. The dashboard Keys page creates Haider API keys, not Apify credentials. A catalog row showing Your key confirms credential presence; the Live filter and callable count also check actor readiness.
Limits#
| Scope | Bound |
|---|---|
| Discovery list | 5 tools by default, 1 to 20 per page; responses at most 64 KiB |
| Input schema | 8 KiB of encoded JSON per schema |
| Invocation | 512 KiB request envelope; tool schema limits also apply |
| Jobs | 2 unsettled jobs per caller, 32 workers globally, 60 new admitted bindings per caller per rolling minute |
| Results | 64 KiB per response including envelope; at most 100 pages, subject to the tool's lower cap |
| Custom HTTP | 100 active tools per owner; one page, at most 10 seconds, no long jobs |
| Standard upstream HTTP | 1 MiB request/decompressed response, 4 MiB gzip transfer, 10 seconds; at most two same-origin redirects |
| Curated image upstream HTTP | 12 MiB request/decompressed response, 48 MiB gzip transfer, 180 seconds; redirects refused |
The larger upstream profile is restricted to three fixed image POST endpoints. Custom tools cannot select it. Both profiles cap response headers at 16 KiB. Read each tool's describe response for its own tighter limits; an upstream bound does not enlarge the API result envelope.
Errors#
Errors use {"error":{"type":"...","message":"..."}}. Read the stable type and any reason, job ID, receipt or funding links. Preserve unknown reasons without automatic retry loops.
| Status and type | Action |
|---|---|
400 invalid | Correct the query, schema input, projection or spending ceiling deliberately |
400 policy | Review the refused image request |
401 key | Supply one valid, unrevoked Bearer key |
402 plan / credits | Use error.upgrade_url or error.topup_url; active plan, grace and budget checks apply |
403 hold | Resolve the caller or billed-owner hold |
404 not_found | The tool or job is unknown, private, expired or no longer accessible |
409 idempotency | Recover the original request binding |
409 tool_unavailable | Read the reason and availability state |
409 connection | Reconnect the caller's social account |
413 size / too_large | Reduce the request, result or extraction work |
429 rate | Respect Retry-After; preserve the original binding |
502 upstream_failure / 504 upstream_timeout | Read the job and receipt before deciding what to do next |
500 internal | Preserve job evidence; an uncertain outcome does not authorize a replacement call |
Owner keys#
The site owner configures supported provider keys and enablement in /admin/tools. This uses the owner's signed-in session; an hk- key alone does not authorize administration. Stored keys are never returned, and each supported key is bound to its upstream origin.
OAuth app client ID/secret pairs are deployment settings, separate from the single-key editor. TOOLS_ENABLED must be enabled on the deployment before the tools APIs are mounted.
Use the public catalog to inspect the rollout and API Keys to create caller credentials.