---
title: "What the brand gets"
url: https://services.dev/docs/examples/tax/surfaces
captured: [tax-surfaces.txt]
---
# What the brand gets

URL: https://services.dev/docs/examples/tax/surfaces

> The tax brand's API, CLI, MCP server, SDK, Site, Docs and App, each generated from its files, in its own words of return, taxpayer, review and preparer.

*tax's words: return is a job, taxpayer is a subject, review is a task, preparer is a member (examples/tax/brand.ts).*

Ten files of Services, and the brand gets seven surfaces. Each one below is what the brand serves for this folder. `brand.ts` sets the words, so a business, an agent or a preparer reads return, taxpayer, review and preparer everywhere, and never the words services.dev uses inside.

## API

Every route its `openapi.json` lists, one for each of the ten Services. Time adds the taxpayer's routes, the clocks with their acknowledge, satisfy and choose calls, and the subscriptions:

```txt
→ GET /openapi.json
```

```txt title="magic values: none"
  servers https://apis.tax (tax's own origin) · http://localhost:8787 (Where dev serves it now)
  POST GET    /returns
  POST        /amended-return
  POST        /annual-return
  POST        /carryforward-watch
  POST        /estimate
  POST        /information-returns
  POST        /notice-response
  POST        /question
  POST        /tax-plan
  POST        /transcript
  POST        /year-end-close
  GET         /amended-return.json
  GET         /annual-return.json
  GET         /carryforward-watch.json
  GET         /estimate.json
  GET         /information-returns.json
  GET         /notice-response.json
  GET         /question.json
  GET         /tax-plan.json
  GET         /transcript.json
  GET         /year-end-close.json
  POST        /amended-return/waitlist
  POST        /annual-return/waitlist
  POST        /carryforward-watch/waitlist
  POST        /estimate/waitlist
  POST        /information-returns/waitlist
  POST        /notice-response/waitlist
  POST        /question/waitlist
  POST        /tax-plan/waitlist
  POST        /transcript/waitlist
  POST        /year-end-close/waitlist
  GET         /catalog
  GET         /catalog/{id}
  GET         /returns/{id}
  POST        /returns/{id}/accept
  POST        /returns/{id}/send_back
  POST        /returns/{id}/cancel
  POST        /returns/{id}/end
  POST        /returns/{id}/again
  POST        /returns/{id}/policy
  POST        /returns/{id}/signals
  POST GET    /returns/{id}/messages
  GET         /returns/{id}/record
  POST        /{portal}/returns/{id}/approve
  POST        /{portal}/join
  POST        /{portal}/preparers/{id}/verify
  POST        /me/availability
  GET POST    /me/ledger
  GET         /me/ledger/checks
  GET         /me/missed
  GET         /reviews
  GET         /reviews/{id}
  GET         /reviews/{id}/sheet
  POST        /reviews/{id}/pass
  POST        /reviews/{id}/claim
  POST        /reviews/{id}/clear
  GET         /reviews/{id}/packet
  POST        /reviews/{id}/release
  POST        /owner/reviews/{id}/offer
  POST        /reviews/{id}/attest
  POST        /reviews/{id}/send_back
  POST        /reviews/{id}/decline
  POST        /reviews/{id}/recuse
  POST        /reviews/{id}/extend
  POST        /reviews/{id}/contest
  POST        /reviews/{id}/messages
  GET         /taxpayers
  GET         /taxpayers/{id}
  GET         /me/taxpayers
  POST        /taxpayers/{id}/withdraw
  GET         /clocks
  GET         /clocks/{id}
  POST        /clocks/{id}/ack
  POST        /clocks/{id}/satisfy
  POST        /clocks/{id}/choose
  POST        /owner/clocks/{id}/assign
  GET         /subscriptions
  GET         /subscriptions/{id}
  POST        /subscriptions/{id}/cancel
  POST        /owner/preparers/{id}/login
  GET POST    /asks/{id}
  POST        /asks/{id}/revoke
  POST        /asks/{id}/reissue
  GET         /returns/{id}/files
  PUT GET     /returns/{id}/files/{sha256}
  GET         /returns/{id}/export
  GET         /owner/returns/{id}
  POST        /keys
  POST        /keys/{key}
  POST        /test_clocks
  POST        /test_clocks/{id}/advance
  GET POST    /events
  GET         /events/stream
  POST GET    /watches
  DELETE      /watches/{id}
  POST        /watches/{id}/replay
  GET         /index.json
  GET         /healthz
  GET         /fixtures
  GET         /.well-known/agents.json
  GET         /openapi.json
  GET         /llms.txt
  GET         /manifest.json
  GET         /pricing
  GET         /verify/suite.json
```

## CLI

The help, run in the brand's folder:

```bash
npx services.dev help
```

```txt title="magic values: none"
  clocks assign <clock> <preparer>  assign the preparer who answers for a clock
  returns get <return>              read a return
  returns list                      the buyer's returns, newest first
  taxpayers list                    the taxpayers your returns joined
  taxpayers get <taxpayer>          read a taxpayer
  clocks list                       the clocks your returns and their taxpayers run
  clocks get <clock>                read a clock
  clocks ack <clock>                acknowledge a clock you answer for
  clocks satisfy <clock>            close a clock you answer for, on evidence on the record
  clocks choose <clock> <option>    choose one of a clock's lapse options at its date
  subscriptions list                your subscriptions
  subscriptions get <subscription>  read a subscription
  subscriptions cancel <subscription>  cancel a subscription
  me taxpayers                      the taxpayers where you are of record
  taxpayers withdraw <taxpayer> <successor>  withdraw as the preparer of record, naming your successor
  test-clocks create <frozen_at>    make a test clock frozen at a time
  test-clocks advance <clock> <to>  move a test clock to a time, or by a span
  get <return>                      returns get
  tick <span> [--test-clock <tc_>] [--market <m>]  test-clocks advance: move dev's own clock, or --test-clock that one, such as 7d; --market checks dev's simulated market
```

## MCP and SDK

The buyer toolset an agent lists, then the typed client `services.dev sdk` writes. An agent orders and reads returns, and never signs, files or consents for anyone:

```txt
→ tools/list
```

```txt title="magic values: none"
  order_return              Order any of tax's 10 Services: name it in service, with its own fields.
  get_return                Read a return, now or after waiting up to wait seconds while it works or waits on a person.
  list_returns              The buyer's returns, newest first: OK, or EMPTY when none match.
  accept_return             Accept a delivered return.
  send_back_return          Send a return back with a note, and the AI redoes it: a delivered one as the buyer, a waiting one as the person at the line.
  cancel_return             Cancel a return before delivery.
  end_return                End a return at one of its ends, as that end's by allows.
  reorder_return            Order an ended return again, or a follow-on Service its end offers: a new return, with from on its record.
  set_return_policy         Set a return's policy values within their bounds: mechanics from the buyer or the brand's console, merits from the client alone.
  send_return_signal        Raise one of the Service's inbound signals.
  send_return_message       Say something in the return's thread as the client.
  list_return_messages      Read the return's messages, oldest first: one resource with the posts.
  reissue_ask               Reissue an open ask's link, to hand to its party again.

# SDK: the generated client's namespaces and their methods
  amendedReturn       order
  annualReturn        order
  carryforwardWatch   order
  estimate            order
  informationReturns  order
  noticeResponse      order
  question            order
  taxPlan             order
  transcript          order
  yearEndClose        order
  returns             get · wait · list · accept · sendBack · cancel · end · again · setPolicy · signal · message · messages · record · files.list · files.put · files.get
  clocks              list · get · ack · satisfy · choose
  subscriptions       list · get · cancel
  taxpayers           list · get
  asks                reissue
  testClocks          create · advance
  events              list · stream · send
  watches             create · list · delete · replay
```

## Site

The head of the annual return's page, as a browser gets it:

```txt
→ GET /annual-return   # accept: text/html
```

```txt title="magic values: none"
  Annual Return
  Returns, e-filed.
  $1,800 per return, filed 5 days before its deadline, 20% off if late, or we pay the penalty and its interest, up to $5,000, after we ask the IRS to take it off, charged when file is accepted. · A signer signs at sign, as the paid preparer for the brand's firm. The owner signs the §7216 consent first, uploads at organizer and signs Form 8879-CORP or 8879-PE at authorize.
  curl http://localhost:8787/returns \
```

## Docs

The brand's own `llms.txt`: what it sells, then each Service with its price and who signs:

```txt
→ GET /llms.txt
```

```txt title="magic values: none"
# tax

> tax sells Amended Return, Annual Return, Carryforward Watch, Estimated Payment, Information Returns, Notice Response, Tax Question, Tax Plan, Tax Transcript and Year-End Close. Order over MCP at http://localhost:8787/mcp or HTTP; every price is at http://localhost:8787/pricing.

## Amended Return

Amended returns. $900 per return, within 30 days, charged when file or aar is accepted. A preparer does the prepare step. A signer signs at sign, as the paid preparer for the brand's firm. The owner signs Form 8879-CORP or 8879-PE at authorize.

MCP: order_amended_return at http://localhost:8787/mcp

```
curl http://localhost:8787/returns -H 'content-type: application/json' -d '{"service":"amended-return","ein":"12-3456789","tax_year":"2026","entity":"C corp","jurisdictions":["US","US-CA"],"books":"https://books.example/acme","max_usd":900,"key":"any-string-you-choose"}'
```

…
```

## App

One brand serves three apps, each at its own path: the customer portal, the preparers' delivery portal and the owner console:

```txt
→ GET /portal   # the customer portal, accept: text/html
```

```txt title="magic values: none"
  Your returns
→ GET /practitioners   # the delivery portal, in a preparer's own session, accept: text/html
  Practitioners
→ GET /console   # the owner console, accept: text/html
  Owner console
```

[The customer portal](https://services.dev/docs/examples/tax/customer-portal.md), [the delivery portal](https://services.dev/docs/examples/tax/delivery-portal.md) and [the owner console](https://services.dev/docs/examples/tax/console.md) show their screens. [Brand()](https://services.dev/docs/service/brand.md) covers the words.

---

- Up: [The tax example](https://services.dev/docs/examples/tax.md)
- Previous: [The money](https://services.dev/docs/examples/tax/money.md)
- Next: [The rules table](https://services.dev/docs/examples/tax/rules.md)