Loods API v1

Docs · API v1

Reference

Every endpoint, error and limit of API v1 on one page.

Endpoints

MethodPathWhat it doesAnswers
POST/v1/key-pickupsCollect your key with the link you were sent. No key needed200
GET/v1/meWho this key belongs to200
PATCH/v1/meSet or clear your webhook200
GET/v1/channelsEvery channel of yours200
GET/v1/channels/{ref}One channel200
PUT/v1/channels/{ref}Create or replace a channel201 · 200
DELETE/v1/channels/{ref}Stop reading it and forget it204
GET/v1/eventsEvents, oldest first200
GET/v1/events/{id}One event, with its delivery200
POST/v1/events/{id}/redeliverPush it again202
POST/v1/interpret/leadRead a lead200
POST/v1/interpret/messageRead a message against your intents200
POST/v1/draftFill the gaps in your outline200
POST/v1/extractAnswer in your own schema200
POST/v1/whatsapp/messagesSend a message201
GET/v1/whatsapp/media/{media_id}Stream the bytes of received media200
GET/v1/mail/attachments/{id}Stream the bytes of a mail attachment200
GET/v1/creditsYour balance, and when it last moved200
PATCH/v1/creditsSet or clear the low-balance threshold200
GET/v1/credits/ledgerEvery credit movement, newest first200
GET/v1/credits/usageCredits spent per task200
GET/v1/credits/usage/dailyThe same, broken down by day200
GET/v1/billing/plansThe plans you may take200
POST/v1/billing/subscriptionStart a subscription200
GET/v1/billing/subscriptionWhat you are on, and what it costs200
DELETE/v1/billing/subscriptionCancel at the end of the period204
GET/v1/billing/packagesThe top-up packs200
POST/v1/billing/checkoutBuy a pack200
GET/v1/billing/channelsChannels connected, carried and charged200
POST/in/form/{channel_id}A submission from one of your own pages. No key: a browser posts this204 · 303

Errors

Branch on code. type says whose problem it is.

TypeStatusCodesWhat to do
invalid_request400 · 422invalid_request
idempotency_key_required
form_not_declared		Fix the request. fields says what is wrong with each field. form_not_declared is the page being refused rather than the visitor: no retry helps, and the channel’s forms list is what to look at.
authentication_error401invalid_api_keySend a valid key as a bearer token.
not_found404not_foundIt doesn’t exist, or it isn’t yours.
conflict409conflict
idempotency_key_reused
request_in_progress
pickup_used
pickup_expired		The request clashes with what exists: a channel’s type, a number already connected, a reused key, or a redelivery with no webhook. A key link that was used or ran out is asked for again, and one used by somebody else is reported.
rate_limited429rate_limitedSlow down: 600 requests a minute per client. A form channel is counted per channel instead — see Limits.
upstream_error502model_unreachable
model_error
answer_truncated
answer_invalid
answer_incomplete
whatsapp_error		The model or the messaging platform failed. A model call is safe to try again. A send is safe to retry with the same Idempotency-Key.
unavailable503unavailableLoods is down for a moment. Try again shortly.
api_error500api_errorSomething went wrong in Loods. Try again. If it keeps happening, report the time and the path you called.

Limits

WhatLimit
Requests per client600 a minute
Form submissions per channel600 an hour
Form submissions, every channel together300 a minute
Channel ref64 characters: a–z 0–9 . _ -
Webhook answer2xx within 15 s
Retries of a pushabout 2 days
Events kept30 days
Signature clock tolerance300 s
Lead text read20,000 characters
guidance10,000 characters
Draft gaps20, of 2,000 characters each
companion.max_chars20 to 4096
Message text4096 characters
Reply buttons3, titles of 20 characters
Idempotency-Key255 characters
Idempotency-Key remembered1 day
Media idsabout 30 days