API reference

• API

  https://tellfield.com/api/v1

• MCP server

  https://tellfield.com/api/mcp, streamable HTTP

• Key

  Authorization: Bearer tf_…

• OpenAPI

  https://tellfield.com/api/v1/openapi.json

Bodies are JSON, sent with Content-Type: application/json. Every tool takes the same fields as its call: query, path and body together. Errors and limits are in the guide for agents.

MCP tools

• sign_up

  Scope: none

  What it does: Sign your person up

• list_plans

  Scope: none

  What it does: List the plans

• list_markets

  Scope: none

  What it does: List the markets

• get_account

  Scope: read

  What it does: Get the account

• list_reports

  Scope: read

  What it does: List reports

• get_report

  Scope: read

  What it does: Get a report

• get_watchlist

  Scope: read

  What it does: Get the watchlist

• find_company

  Scope: watchlist

  What it does: Find a company

• set_watchlist

  Scope: watchlist

  What it does: Set the watchlist

• add_market

  Scope: watchlist

  What it does: Add a market

• start_plan

  Scope: billing

  What it does: Start or change a plan

• list_keys

  Scope: keys

  What it does: List keys

• create_key

  Scope: keys

  What it does: Make a key

• revoke_key

  Scope: keys

  What it does: Revoke a key

No key

Sign your person up

POST /api/v1/signup

Asks for a Tellfield account for your person, or a key to the account they have. Returns an API key at once; it works once they confirm by the link we mail them (within 24 hours). Until then calls answer 401 with code confirmation_pending: poll get_account about once a minute. Send the market and plan to set up with it.

No key needed. MCP tool: sign_up. Answers 202 when it works.

• email

  Type: string

  Required: yes

  What it is: Your person's work address. We mail them the link to confirm.

• agent_name

  Type: string

  Required: yes

  What it is: What your person calls you, shown in the mail and on the confirm page, e.g. "Research assistant".

• scopes

  Type: list of read, watchlist, billing, keys

  What it is: What the key may do. Leave empty for everything; read is always in.

• watchlist

  Type: object

  What it is: The market to set up once your person confirms.

• watchlist.market

  Type: outbound-sales-tools, compliance-automation-for-audits, other

  Required: yes

  What it is: One market slug from /api/v1/markets. "other" needs market_description.

• watchlist.market_description

  Type: string

  What it is: Your market in a few words, when market is "other".

• watchlist.brand

  Type: object

  Required: yes

  What it is: Your own brand.

• watchlist.brand.name

  Type: string

  What it is: The brand as people write it, e.g. "Northwind". Optional when website is given.

• watchlist.brand.website

  Type: string

  What it is: The brand's own site, e.g. "northwind.example". Preferred.

• watchlist.brand.linkedin

  Type: string

  What it is: Its LinkedIn company page address. Optional: we find it.

• watchlist.brand.x

  Type: string

  What it is: Its X handle. Optional: we find it.

• watchlist.brand.aliases

  Type: list of string

  What it is: Other names people use for it.

• watchlist.competitors

  Type: list of object

  What it is: Up to 10 competitors.

• watchlist.competitors[].name

  Type: string

  What it is: The brand as people write it, e.g. "Northwind". Optional when website is given.

• watchlist.competitors[].website

  Type: string

  What it is: The brand's own site, e.g. "northwind.example". Preferred.

• watchlist.competitors[].linkedin

  Type: string

  What it is: Its LinkedIn company page address. Optional: we find it.

• watchlist.competitors[].x

  Type: string

  What it is: Its X handle. Optional: we find it.

• watchlist.competitors[].aliases

  Type: list of string

  What it is: Other names people use for it.

• plan

  Type: object

  What it is: The plan to pick for that market. Paying stays with your person, by a checkout link.

• plan.tier

  Type: market, growth, full

  Required: yes

  What it is: A plan key from /api/v1/plans.

• plan.part

  Type: competitors, you

  What it is: For "growth" only: the one part it adds.

• plan.interval

  Type: month, year

List the plans

GET /api/v1/plans

The plans, their prices and what each adds. Each market has its own plan.

No key needed. MCP tool: list_plans. Answers 200 when it works.

List the markets

GET /api/v1/markets

The markets we read, by slug. Pick "other" and describe yours when none fits.

No key needed. MCP tool: list_markets. Answers 200 when it works.

Read

Get the account

GET /api/v1/account

The team, what this key may do, and each market with its plan and where its brief stands.

Scope: read. MCP tool: get_account. Answers 200 when it works.

List reports

GET /api/v1/reports

The weeks that have a report for one market, newest first.

Scope: read. MCP tool: list_reports. Answers 200 when it works.

• market

  In: query

  Type: integer

  What it is: One of the team's market ids, from get_account or get_watchlist. Leave empty for the first market.

Get a report

GET /api/v1/reports/{week}

One weekly report, whole or one section. Leave week empty (or "latest") for the latest.

Scope: read. MCP tool: get_report. Answers 200 when it works.

• week

  In: path

  Type: string

  Required: yes

  What it is: ISO week, e.g. 2026-W45, or "latest".

• section

  In: query

  Type: summary, worked, competitors, you, changes, teams

  What it is: Only this part of the report.

• market

  In: query

  Type: integer

  What it is: One of the team's market ids, from get_account or get_watchlist. Leave empty for the first market.

Get the watchlist

GET /api/v1/watchlist

One market's own brand and competitors, and every market the team watches.

Scope: read. MCP tool: get_watchlist. Answers 200 when it works.

• market

  In: query

  Type: integer

  What it is: One of the team's market ids, from get_account or get_watchlist. Leave empty for the first market.

Watchlist

Find a company

GET /api/v1/company

Looks a company up by its website (best) or name: its name, site and our market for it, when we read one.

Scope: watchlist. MCP tool: find_company. Answers 200 when it works.

• website

  In: query

  Type: string

  What it is: e.g. "northwind.example"

• name

  In: query

  Type: string

  What it is: e.g. "Northwind"

Set the watchlist

PUT /api/v1/watchlist

Sets one market's market, own brand and competitors, replacing what was there. Website first: give each brand's site and we fill in the name and find its pages. With no market id it sets the first market, making it when the team has none. A market without a plan gets its first brief free.

Scope: watchlist. MCP tool: set_watchlist. Answers 200 when it works.

• market

  In: query

  Type: integer

  What it is: One of the team's market ids, from get_account or get_watchlist. Leave empty for the first market.

• market

  Type: outbound-sales-tools, compliance-automation-for-audits, other

  Required: yes

  What it is: One market slug from /api/v1/markets. "other" needs market_description.

• market_description

  Type: string

  What it is: Your market in a few words, when market is "other".

• brand

  Type: object

  Required: yes

  What it is: Your own brand.

• brand.name

  Type: string

  What it is: The brand as people write it, e.g. "Northwind". Optional when website is given.

• brand.website

  Type: string

  What it is: The brand's own site, e.g. "northwind.example". Preferred.

• brand.linkedin

  Type: string

  What it is: Its LinkedIn company page address. Optional: we find it.

• brand.x

  Type: string

  What it is: Its X handle. Optional: we find it.

• brand.aliases

  Type: list of string

  What it is: Other names people use for it.

• competitors

  Type: list of object

  What it is: Up to 10 competitors.

• competitors[].name

  Type: string

  What it is: The brand as people write it, e.g. "Northwind". Optional when website is given.

• competitors[].website

  Type: string

  What it is: The brand's own site, e.g. "northwind.example". Preferred.

• competitors[].linkedin

  Type: string

  What it is: Its LinkedIn company page address. Optional: we find it.

• competitors[].x

  Type: string

  What it is: Its X handle. Optional: we find it.

• competitors[].aliases

  Type: list of string

  What it is: Other names people use for it.

Add a market

POST /api/v1/watchlist

Adds another market to watch, with its own brand and competitors (up to 5 markets). Each market has its own plan.

Scope: watchlist. MCP tool: add_market. Answers 201 when it works.

• market

  Type: outbound-sales-tools, compliance-automation-for-audits, other

  Required: yes

  What it is: One market slug from /api/v1/markets. "other" needs market_description.

• market_description

  Type: string

  What it is: Your market in a few words, when market is "other".

• brand

  Type: object

  Required: yes

  What it is: Your own brand.

• brand.name

  Type: string

  What it is: The brand as people write it, e.g. "Northwind". Optional when website is given.

• brand.website

  Type: string

  What it is: The brand's own site, e.g. "northwind.example". Preferred.

• brand.linkedin

  Type: string

  What it is: Its LinkedIn company page address. Optional: we find it.

• brand.x

  Type: string

  What it is: Its X handle. Optional: we find it.

• brand.aliases

  Type: list of string

  What it is: Other names people use for it.

• competitors

  Type: list of object

  What it is: Up to 10 competitors.

• competitors[].name

  Type: string

  What it is: The brand as people write it, e.g. "Northwind". Optional when website is given.

• competitors[].website

  Type: string

  What it is: The brand's own site, e.g. "northwind.example". Preferred.

• competitors[].linkedin

  Type: string

  What it is: Its LinkedIn company page address. Optional: we find it.

• competitors[].x

  Type: string

  What it is: Its X handle. Optional: we find it.

• competitors[].aliases

  Type: list of string

  What it is: Other names people use for it.

Plans

Start or change a plan

POST /api/v1/checkout

Picks a plan for one market and returns a link for your person: Stripe Checkout to pay for a new plan, or a page to confirm a change to a plan they pay for. Nothing is charged until they pay or confirm there.

Scope: billing. MCP tool: start_plan. Answers 200 when it works.

• tier

  Type: market, growth, full

  Required: yes

  What it is: A plan key from /api/v1/plans.

• part

  Type: competitors, you

  What it is: For "growth" only: the one part it adds.

• interval

  Type: month, year

• market

  Type: integer

  What it is: One of the team's market ids, from get_account or get_watchlist. Leave empty for the first market.

Keys

List keys

GET /api/v1/keys

The team's keys that work: name, start of the key, scopes and when each was last used.

Scope: keys. MCP tool: list_keys. Answers 200 when it works.

Make a key

POST /api/v1/keys

Makes a key with no more scopes than this one. The key is shown once, in this answer.

Scope: keys. MCP tool: create_key. Answers 201 when it works.

• name

  Type: string

  Required: yes

  What it is: Who will use it, e.g. "Weekly planner".

• scopes

  Type: list of read, watchlist, billing, keys

  What it is: Leave empty for read only.

Revoke a key

DELETE /api/v1/keys/{id}

Stops one of the team's keys at once. Only a key with no more scopes than this one.

Scope: keys. MCP tool: revoke_key. Answers 200 when it works.

• id

  In: path

  Type: integer

  Required: yes

  What it is: The key id, from list_keys.