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.

Stars 15,297
Forks 1,022

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, and method
  • 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 in path_params
  • Middleware can run before handlers via middleware_function_ids in the trigger config — see iii-http-middleware for 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 initialization
  • registerFunction(id, handler) — define the route handler
  • registerTrigger({ type: 'http', config: { api_path, http_method } }) — bind path and method
  • req.body — parsed request body for POST/PUT
  • req.path_params — extracted path parameters
  • return { status_code: 200, body: { data }, headers: { 'Content-Type': 'application/json' } } — response shape
  • const 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_params for 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 inspect req.headers for 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-processing for the background work.
  • If the task is specifically about middleware chains (auth, logging, rate-limiting), prefer iii-http-middleware.
  • Stay with iii-http-endpoints when iii owns the route and handles the inbound request directly.

When to Use

  • Use this skill when the task is primarily about iii-http-endpoints in 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.

Expand your agent's capabilities with these related and highly-rated skills.

iii-hq/iii

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.

15,297 1,022
Explore
iii-hq/iii

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.

15,297 1,022
Explore
iii-hq/iii

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.

15,297 1,022
Explore
iii-hq/iii

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.

15,297 1,022
Explore
iii-hq/iii

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.

15,297 1,022
Explore
iii-hq/iii

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.

15,297 1,022
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results