Agent skill
iii-http-endpoints
Exposes iii functions as REST API endpoints. Use when building HTTP APIs, webhooks, or inbound request handling where iii owns the route.
Install this agent skill to your Project
npx add-skill https://github.com/iii-hq/iii/tree/main/skills/iii-http-endpoints
SKILL.md
HTTP Endpoints
Comparable to: Express, Fastify, Flask
Key Concepts
Use the concepts below when they fit the task. Not every HTTP endpoint needs all of them.
- Each route is a registered function bound to a path and method via an HTTP trigger
- The handler receives an ApiRequest object containing
body,path_params,headers, andmethod - Handlers return
{ status_code, body, headers }to shape the HTTP response - iii-http serves all registered routes on port 3111
- Path parameters use colon syntax (e.g.
/users/:id) and arrive inpath_params - Middleware can run before handlers via
middleware_function_idsin the trigger config — seeiii-http-middlewarefor details
Architecture
HTTP request
→ iii-http (port 3111)
→ registerTrigger route match (method + path)
→ registerFunction handler (receives ApiRequest)
→ { status_code, body, headers } response
iii Primitives and HTTP Trigger Config Used
| Primitive | Purpose |
|---|---|
registerFunction |
Define the handler for a route |
registerTrigger({ type: 'http' }) |
Bind a route path and method to a function |
config: { api_path: '/path', http_method: 'GET' } |
Route configuration on the trigger |
config: { ..., middleware_function_ids: [...] } |
Optional middleware chain before the handler |
Reference Implementation
See ../references/http-endpoints.js for the full working example — a REST API with parameterized routes handling GET and POST requests.
Also available in Python: ../references/http-endpoints.py
Also available in Rust: ../references/http-endpoints.rs
Common Patterns
Code using this pattern commonly includes, when relevant:
registerWorker(url, { workerName })— worker initializationregisterFunction(id, handler)— define the route handlerregisterTrigger({ type: 'http', config: { api_path, http_method } })— bind path and methodreq.body— parsed request body for POST/PUTreq.path_params— extracted path parametersreturn { status_code: 200, body: { data }, headers: { 'Content-Type': 'application/json' } }— response shapeconst logger = new Logger()— structured logging per handler
Adapting This Pattern
Use the adaptations below when they apply to the task.
- Add more routes by registering additional functions and HTTP triggers with distinct paths or methods
- Use
path_paramsfor resource identifiers (e.g./orders/:orderId) - Return appropriate status codes (201 for creation, 404 for not found, 400 for bad input)
- For authenticated routes, use middleware (
middleware_function_ids) or inspectreq.headersfor tokens or API keys - Chain work behind an endpoint by enqueuing to a queue after returning a 202 Accepted
- For reusable auth, logging, or rate-limiting before handlers, prefer
iii-http-middleware
Pattern Boundaries
- If the task is about calling external HTTP APIs from iii functions, prefer
iii-http-invoked-functions. - If async processing is needed behind the endpoint, prefer
iii-queue-processingfor the background work. - If the task is specifically about middleware chains (auth, logging, rate-limiting), prefer
iii-http-middleware. - Stay with
iii-http-endpointswhen iii owns the route and handles the inbound request directly.
When to Use
- Use this skill when the task is primarily about
iii-http-endpointsin the iii engine. - Triggers when the request directly asks for this pattern or an equivalent implementation.
Boundaries
- Never use this skill as a generic fallback for unrelated tasks.
- You must not apply this skill when a more specific iii skill is a better fit.
- Always verify environment and safety constraints before applying examples from this skill.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
iii-dead-letter-queues
Inspects and redrives jobs that exhausted all retries. Use when handling failed queue jobs, debugging processing errors, or implementing retry strategies.
iii-cron-scheduling
Registers cron triggers with 7-field expressions to run functions on recurring schedules. Use when scheduling periodic jobs, timed automation, crontab replacements, cleanup routines, report generation, health checks, batch processing, or any task that should run every N seconds, minutes, hours, or on a weekly/monthly calendar.
iii-http-invoked-functions
Registers external HTTP endpoints as iii functions using registerFunction(id, HttpInvocationConfig). Use when adapting legacy APIs, third-party webhooks, or immutable services into triggerable iii functions, especially when prompts ask for endpoint maps like { path, id } iterated into registerFunction calls.
iii-channels
Binary streaming between workers via channels. Use when building data pipelines, file transfers, streaming responses, or any pattern requiring binary data transfer between functions.
iii-event-driven-cqrs
Implements CQRS with event sourcing on the iii engine. Use when building command/query separation, event-sourced systems, or fan-out architectures where commands publish domain events and multiple read model projections subscribe independently.
iii-agentic-backend
Creates and orchestrates multi-agent pipelines on the iii engine. Use when building AI agent collaboration, agent orchestration, research/review/synthesis chains, or any system where specialized agents hand off work through queues and shared state.
Didn't find tool you were looking for?