Endpoints and jobs

Cells can declare custom HTTP endpoints and background jobs in addition to queries and mutations.

Endpoints

Endpoints are custom HTTP routes that do not fit the query/mutation pattern. They are useful for:

Webhook receivers.
File uploads.
Custom API shapes.
Proxying to external services.

Definition

import { endpoint } from "@anvil-cloud/runtime";

export default app({
  endpoints: {
    webhook: endpoint({
      method: "POST",
      path: "/webhooks/stripe",
      handler: async (ctx) => {
        const payload = ctx.request.body;
        // verify signature, record event, enqueue job
        return { received: true };
      },
    }),
  },
});

Request context

Endpoint handlers receive the same ctx as queries and mutations, plus ctx.request.body, ctx.request.headers, and ctx.request.query.

Routing

Local runtime maps /api/* to declared endpoints. The endpoint path is relative to /api:

POST /api/webhooks/stripe  ->  webhook endpoint

AWS preview routes API Gateway or Lambda Function URL events to the same endpoint handler.

Jobs

Jobs are background handlers that run outside the request path.

On-demand jobs

import { job } from "@anvil-cloud/runtime";

export default app({
  jobs: {
    sendEmail: job({
      handler: async (ctx, payload) => {
        // send email, update status
      },
    }),
  },
});

Enqueue from a query, mutation, or endpoint:

await ctx.jobs.enqueue("sendEmail", { to: user.email, subject: "Welcome" });

Scheduled jobs

import { job } from "@anvil-cloud/runtime";

export default app({
  capabilities: {
    scheduledJobs: true,
  },
  jobs: {
    nightlyCleanup: job({
      schedule: "0 2 * * *",
      overlap: "skip",
      timeoutMs: 30_000,
      handler: async (ctx) => {
        // run cleanup
      },
    }),
  },
});

Scheduled jobs require capabilities.scheduledJobs. Guard rejects scheduled jobs without the capability declaration. Local schedules support rate(1 hour), @every 5m, and five-field cron expressions. Missed local runs while the runtime is stopped are skipped, not replayed.

Local job execution

Local runtime stores queued jobs in .anvil/local/jobs.json, and scheduled job state plus run history in .anvil/local/schedules.json. You can trigger a queued job manually:

curl -X POST http://localhost:8787/_anvil/jobs/run/sendEmail \
  -H "Content-Type: application/json" \
  -d '{"to":"user@example.com"}'

You can inspect and trigger scheduled jobs through the CLI:

anvil-cloud schedules list --json
anvil-cloud schedules run nightlyCleanup --payload '{}' --json

AWS job execution

AWS preview maps:

On-demand jobs to SQS queues + Lambda triggers.
Scheduled jobs to EventBridge rules invoking the Lambda runtime.
ctx.events.publish to EventBridge when capabilities.events is declared.
Repeatedly failing queued jobs to a Cell-owned SQS dead-letter queue after three receives, with 14 day retention for alpha debugging.

Limitations

Local job scheduling is simple and best-effort. It is not a production job scheduler.
Job retry timing and dead-letter retention remain adapter-specific.