ellipsis.dev

You define an Ellipsis agent by committing a YAML file (for example agent.yaml, standup-automator.yaml, or triage-issues.yaml) into your repository. The file declares the agent's name, description, trigger, session harness and model, prompt, environment, repositories, hooks, and budget. Ellipsis reads that config and runs the agent in its managed cloud infrastructure, so you never provision compute or wire up permissions yourself. This works if you have the Ellipsis app installed on GitHub and are comfortable editing repo files; the examples below follow the structure shown in Ellipsis's own documentation.

The core shape of an agent file

Every agent file starts with an ellipsis block and then describes what the agent is and when it runs. The fields you'll use most:

Step 1: Create the file and name the agent

Add a YAML file to your repo. The ellipsis key is the root, and kind: agent tells Ellipsis this is an agent definition rather than something else.

ellipsis:
  kind: agent
  name: triage-issues
  prompt: Label new issues and find duplicates.
  environment:
    repositories:
      - name: web-repo

The name is how you and the platform refer to the agent; prompt is the actual task. The environment.repositories list scopes which repos the agent can touch.

Step 2: Choose a trigger

Triggers decide when the agent runs. Two forms appear in the docs:

Cron (scheduled): run on a fixed schedule.

trigger:
  type: cron
  schedule: "30 8 * * 1-5"

This fires at 08:30 on weekdays — the pattern used by the standup-automator example, which posts a daily digest of merged PRs, pending reviews, and failing CI to Slack.

React (event-driven): run in response to repository activity such as a pushed pull request.

trigger:
  type: react
  pull_request:
    on: [pushed]
  repositories: [api-repo]

The check-api-changes example uses this to inspect changed API routes for missing test coverage whenever a PR is pushed.

Step 3: Pick a harness and model

The session block selects the coding harness and the model. Switching between them is a one-line change — you don't rebuild the agent.

session:
  claude_code:
    model: claude-opus-5-5

To move to a different harness and model, swap the block:

session:
  codex:
    model: gpt-6-sol

The rest of the file (name, prompt, environment) stays the same. This is the mechanism behind Ellipsis's "any agent, any model" claim — the config, not the code, decides what runs.

Step 4: Configure the environment and hooks

The environment block controls what the agent has access to and any setup it needs before running. repositories lists the repos; hooks run shell commands at defined points, such as after checkout.

environment:
  repositories:
    - name: api-repo
  hooks:
    after_checkout: |
      cd api-repo

Use hooks for setup steps your agent needs before it starts its task — installing dependencies, checking out a branch, or preparing a working directory.

Step 5: Set a budget

The budget block caps how much a session can consume, so a runaway agent doesn't keep running.

budget:
  session: 2

Set this deliberately for scheduled or event-driven agents that could otherwise fire repeatedly.

A complete example

Putting the pieces together, a scheduled digest agent looks like this:

ellipsis:
  name: standup-automator
  description: Posts a daily standup digest to Slack
  trigger:
    type: cron
    schedule: "30 8 * * 1-5"
  session:
    claude_code:
      model: claude-opus-4-8
  prompt: |
    Each weekday, summarize yesterday's merged PRs, the reviews still
    waiting, and any failing CI, then post the digest to #engineering
    and @ the right owners.
  budget:
    session: 2

How to verify it works

After committing the file, confirm the agent is registered and triggered as expected. The docs reference an API surface for this — POST /v1/agents to create an agent, POST /v1/agents/{id}/sessions to start a session, and POST /v1/sessions/{id}/messages to message a running session. Use these to check that your YAML parsed into an agent and to start a test session before relying on the trigger.

Common sticking points

• Trigger type mismatch. A cron trigger needs a valid schedule; a react trigger needs the event (for example pull_request.on) and the repos to watch. Mixing fields from both will fail.
• Repo scope. If the agent can't see a repository, check that it's listed under environment.repositories — the trigger's repositories and the environment's list serve different purposes.
• Hooks failing silently. A broken after_checkout command stops the agent before its prompt runs. Test the command locally first.
• Missing budget. Scheduled agents without a budget.session cap can accumulate sessions; set one for anything that fires on a timer.

Once the file is committed and the agent is registered, Ellipsis handles the infrastructure, permissions, logging, and budgets — your job is keeping the YAML accurate as the agent's task changes.

A postal code API returns structured location data for a given ZIP Code or Canadian postal code. A typical response includes the code itself, city, state or province, county, latitude/longitude, and — where available — ZIP+4 detail. More complete services add time zone, area codes, boundary geometry, and demographic fields. You send a code (or an address), and the API sends back a machine-readable record you can store, validate, or display.

This article explains what those responses contain, how requests are usually shaped, and where postal code data fits into real applications.

First, clear up the word "code"

The keyword "code" is overloaded, and that causes real confusion for developers:

• Postal code — the ZIP Code (U.S.) or postal code (Canada) that identifies a delivery area.
• API key — the credential you use to authenticate your requests. It is not postal data.
• Source code — the program you write to call the API.

When someone searches for "postal code API code," they usually want example request/response code for a postal code service. The rest of this article treats it that way.

What a postal code API actually returns

Response fields vary by provider and endpoint, but the core set is fairly consistent. A single-code lookup commonly returns:

Richer datasets add 90+ fields: boundaries, population, income, elevation, and more. You rarely need all of them — request only what your application uses.

A representative JSON response

{
  "postal_code": "90210",
  "city": "Beverly Hills",
  "state": "CA",
  "county": "Los Angeles",
  "latitude": 34.0901,
  "longitude": -118.4065,
  "timezone": "America/Los_Angeles",
  "area_codes": ["310", "424"]
}

XML responses carry the same information in tag form. Choose based on what your stack parses most easily; JSON is the common default.

Common request patterns

Most postal code APIs support four patterns. Knowing which one you need prevents wasted calls.

1. Lookup by code

You have a code and want its details. This is the simplest and fastest call.

GET /lookup?code=90210

2. Reverse lookup by address

You have a street address and want to confirm or complete the code. This is the pattern behind checkout address validation.

GET /validate?street=...&city=...&state=...

3. Radius search

You have a center point and want all codes within a distance. Useful for store locators and delivery zones.

GET /radius?code=90210&miles=10

4. Batch validation

You have a file of addresses and want them cleaned in bulk. Batch endpoints trade latency for throughput and usually have their own limits.

Handling missing and ambiguous matches

Real data is messy. Plan for these cases:

• No match — the code doesn't exist or the address is malformed. Return a clear error rather than a silent empty object.
• Multiple matches — a city name may map to several codes, or a code may span several acceptable city names. Decide whether to pick the primary or return a list.
• Partial match — the street is valid but the ZIP+4 isn't. Fall back to the 5-digit code.
• Stale data — codes are added, retired, and reassigned. Refresh your dataset on a regular schedule.

A practical rule: validate at the point of entry, store the normalized result, and never re-derive it later from raw user input.

Practical use cases

• Checkout address validation — catch typos before shipping, reduce failed deliveries.
• Shipping zone lookup — map a code to a zone, carrier route, or rate table.
• Data enrichment — append county, coordinates, or demographics to existing records.
• Store and service locators — radius search to find nearby branches or coverage areas.
• Territory and tax logic — county and boundary data drive jurisdiction rules.

Licensing and data-source considerations

Postal code data originates with national authorities — USPS in the United States and Canada Post in Canada. Providers license and repackage it, which is why accuracy, update frequency, and field coverage differ between services. Before committing:

• Confirm the data source and how often it refreshes.
• Check whether ZIP+4 and boundary data are included or sold separately.
• Review usage limits and whether batch processing is allowed.
• Read the license terms for redistribution and storage.

Pricing and plan details change, so check the provider's current documentation rather than relying on secondhand figures.

Getting started

1. Decide which request pattern you need (lookup, reverse, radius, or batch).
2. Pick the fields you'll actually store.
3. Write a small test call and inspect the raw response.
4. Add error handling for no-match and ambiguous cases.
5. Cache results where the same codes repeat.

A postal code API is ultimately a translation layer: you give it a code or an address, and it gives back structured location facts. Understand the fields, match them to your use case, and handle the messy edges — that's most of the work.

Ellipsis is a managed cloud platform for running coding agents. You define an agent as a config file in your repository, and Ellipsis runs it in the cloud to build features, fix bugs, review code, and investigate production issues. It fits teams that want automated coding work tied to their own repos but don't want to build and operate the agent infrastructure themselves.

The core idea: agents as config files

Instead of clicking through a UI to set up an assistant, you commit a YAML file to your repo. Ellipsis reads that file and runs the agent according to it. The platform's own framing is "Agents as a Service": you bring the agent definition, Ellipsis handles the infrastructure, permissions, logging, and budgets.

A minimal agent definition from the documentation looks like this:

ellipsis:
  name: standup-automator
  description: Posts a daily standup digest to Slack
  trigger:
    type: cron
    schedule: "30 8 * * 1-5"
  session:
    claude_code:
      model: claude-opus-4-8
      prompt: |
        Each weekday, summarize yesterday's merged PRs, the reviews still
        waiting, and any failing CI, then post the digest to #engineering
        and @ the right owners.
  budget:
    session: 2

The parts you control are visible in the file: the trigger (here a cron schedule), the session harness and model, the prompt, and a session budget. Because the definition lives in the repo, it's versioned alongside the code it acts on.

What the agents actually do

The platform lists three broad use cases:

• Feature generation — agents that build features from a prompt or trigger.
• Background tasks — scheduled or event-driven jobs, like the standup digest above.
• Code review — agents that react to pull request activity.

The documentation's examples show the range. A migration-guard agent and an oncall-assistant agent appear alongside the standup automator. Another example, check-api-changes, triggers on a pull request push and checks changed API routes for missing test coverage:

ellipsis:
  kind: agent
  name: check-api-changes
  trigger:
    type: react
    pull_request:
      on: [pushed]
    repositories: [api-repo]
  session:
    claude_code:
      model: claude-opus-5-5
      prompt: |
        Check the changed API routes for
        missing test coverage.
  environment:
    repositories:
      - name: api-repo
    hooks:
      after_checkout: |
        cd api-...

Note the hooks section: you can run setup commands after checkout, so the agent's environment is prepared the way your project needs.

Any agent, any model

A distinguishing feature is that the harness and model are swappable. The docs describe changing one line to move from Claude Code to Codex, or from Anthropic to OpenAI, without rebuilding the agent. The example diff replaces claude_code with codex and claude-opus-5-5 with gpt-6-sol while keeping the same prompt and environment.

This matters if you want to compare models on the same task, or if your organization standardizes on a different provider later. The agent logic — trigger, prompt, repositories, hooks — stays put.

How you get started

Two entry points are documented:

• Install on GitHub — connect the platform to your repositories.
• API — the docs list endpoints including POST /v1/agents (create an agent), POST /v1/agents/{id}/sessions (start a session), and POST /v1/sessions/{id}/messages (message a session).

There is also a full YAML reference and a documentation site, plus a "Schedule a demo" option. The site shows a Pricing page and a sign-in flow, but the provided material doesn't state prices or whether any tier is free — check the pricing page directly before assuming cost.

What Ellipsis handles for you

The platform's stated responsibilities are the operational layer around the agent:

• Infrastructure — the compute the agent runs on.
• Permissions — access to your repositories and services.
• Logging — a record of what agents did.
• Budgets — per-session limits, as shown by the budget: session: 2 field.

That division is the practical difference from a plain AI coding assistant in your editor. An editor assistant helps a human who is present and driving. Ellipsis runs agents on triggers — schedules, pull request events — without someone watching each step, which is why permissions, logging, and budgets are part of the product rather than afterthoughts.

When this fits and when it doesn't

Ellipsis is a reasonable fit if you want recurring or event-driven coding work (digests, review checks, issue triage) automated against your own repos, and you'd rather write a YAML file than maintain agent runners. It's less obviously a fit if you only want in-editor suggestions while you code, or if you need to confirm exact pricing and limits first — those details aren't in the material here, so verify them on the pricing page and in the documentation before committing.