Public API

v1 stableNo API key

Developer platform

Build on confirmedcompany evidence.

Read-only JSON and embed widgets — the same trust rules as a Hansala company page. Nothing pending. Nothing private.

Base URL

linken-tau.vercel.app/api/v1

Quickstart Embed widgets

GET · companies/{slug}

200

{
  "slug": "example-architecture",
  "name": "Example Architecture",
  "category": "Architecture",
  "city": "Berlin",
  "country": "Germany",
  "website": "https://example.com",
  "verified": true,
  "claimed": true,
  "accepting_clients": true,
  "trust_level": "established",
  "stats": {
    "confirmed_partners": 6,
    "confirmed_references": 4,
    "ongoing_references": 2,
    "confirmed_case_studies": 3
  },
  "assessment": {
    "would_work_again_yes": 9,
    "would_work_again_total": 10,
    "top_strengths": [
      { "key": "reliability", "label": "Reliability", "count": 8 },
      { "key": "deadlines", "label": "Deadlines", "count": 6 }
    ]
  },
  "profile_url": "https://linken-tau.vercel.app/c/example-architecture",
  "generated_at": "2026-07-19T18:00:00.000Z"
}

Surface

REST · JSON

Read-only GET

Evidence

Confirmed only

Same as public profiles

Cache

5 minutes

stale-while-revalidate

Access

Open CORS

No API key required

Overview

The Public API exposes the same confirmed facts you see on a Hansala company page — partners, references, case studies, and assessment aggregates.

Confirmed only

Never pending invites, private emails, or confirmation tokens.

Edge-cache friendly

public, s-maxage=300, stale-while-revalidate=3600. Errors are no-store.

Open CORS

GET and OPTIONS from any origin — drop into any frontend.

No API key

Public GETs are open. Trust comes from confirmation rules, not secrets.

Quickstart

One request. Replace example-architecture with any public profile slug.

First call

Fetch a company in under a minute

GET

curl -sS "https://linken-tau.vercel.app/api/v1/companies/example-architecture" \
  -H "Accept: application/json"

Endpoints

Base path https://linken-tau.vercel.app/api/v1. All responses are JSON. Fields match the public contract in types.ts.

GET/api/v1/companies/{slug}

03.1

Company

Profile, trust level, confirmed stats, and assessment aggregates when anonymity rules allow.

Unclaimed companies return claimed: false with stats and assessment set to null.

Response fields

Field	Type	Description
slug	string	Public URL slug.
name	string	Company display name.
category	string	Primary category.
city	string	City.
country	string	Country.
website	string	Public website URL.
verified	boolean	Whether the profile carries a verified mark.
claimed	boolean	False for unclaimed directory stubs.
accepting_clients	boolean	Owner-set availability for new clients.
trust_level	"member" \| "established" \| "trusted" \| "pillar"	Public Hansala Level (lowercase).
stats	ApiCompanyStats \| null	Confirmed counts. Null when unclaimed.
stats.confirmed_partners	number	Accepted mutual partnerships.
stats.confirmed_references	number	Confirmed finished service references.
stats.ongoing_references	number	Confirmed ongoing service references.
stats.confirmed_case_studies	number	Case studies with client or partner confirmation.
assessment	ApiAssessment \| null	Null until would_work_again_total ≥ 3 (anonymity rule).
assessment.would_work_again_yes	number	Clients who would work again.
assessment.would_work_again_total	number	Total would-work-again answers.
assessment.top_strengths	ApiStrength[]	Top strengths, highest count first.
assessment.top_strengths[].key	string	Catalog key, e.g. "reliability".
assessment.top_strengths[].label	string	Human label.
assessment.top_strengths[].count	number	How many assessments selected this strength.
profile_url	string	Absolute URL to the public profile.
generated_at	string	ISO-8601 generation timestamp.

Request

curl -sS "https://linken-tau.vercel.app/api/v1/companies/example-architecture" \
  -H "Accept: application/json"

ResponseJSON

{
  "slug": "example-architecture",
  "name": "Example Architecture",
  "category": "Architecture",
  "city": "Berlin",
  "country": "Germany",
  "website": "https://example.com",
  "verified": true,
  "claimed": true,
  "accepting_clients": true,
  "trust_level": "established",
  "stats": {
    "confirmed_partners": 6,
    "confirmed_references": 4,
    "ongoing_references": 2,
    "confirmed_case_studies": 3
  },
  "assessment": {
    "would_work_again_yes": 9,
    "would_work_again_total": 10,
    "top_strengths": [
      { "key": "reliability", "label": "Reliability", "count": 8 },
      { "key": "deadlines", "label": "Deadlines", "count": 6 }
    ]
  },
  "profile_url": "https://linken-tau.vercel.app/c/example-architecture",
  "generated_at": "2026-07-19T18:00:00.000Z"
}

GET/api/v1/companies/{slug}/references

03.2

References

Confirmed service references only (max 50). Ongoing engagements are listed first.

Response fields

Field	Type	Description
references	ApiReference[]	Confirmed only, max 50. Ongoing first.
count	number	Length of references.
references[].client_name	string	Client display name.
references[].client_slug	string \| null	Public slug when the client has a claimed Hansala profile.
references[].service	string	Service described.
references[].started_year	string	Start year.
references[].ongoing	boolean	Still active engagement.
references[].ended_year	string \| null	End year when finished.
references[].confirmed_at	string	ISO-8601 when the client confirmed.

Request

curl -sS "https://linken-tau.vercel.app/api/v1/companies/example-architecture/references" \
  -H "Accept: application/json"

ResponseJSON

{
  "references": [
    {
      "client_name": "Nordwerk Holding",
      "client_slug": "nordwerk-holding",
      "service": "Shell construction",
      "started_year": "2023",
      "ongoing": true,
      "ended_year": null,
      "confirmed_at": "2024-11-02T09:14:00.000Z"
    },
    {
      "client_name": "Stadtwerke Spandau",
      "client_slug": null,
      "service": "Electrical fit-out",
      "started_year": "2021",
      "ongoing": false,
      "ended_year": "2022",
      "confirmed_at": "2023-03-18T14:22:00.000Z"
    }
  ],
  "count": 2
}

GET/api/v1/companies/{slug}/case-studies

03.3

Case studies

Case studies with client or partner confirmation (max 20).

Response fields

Field	Type	Description
case_studies	ApiCaseStudy[]	Confirmed only, max 20.
count	number	Length of case_studies.
case_studies[].slug	string	Case study slug.
case_studies[].title	string	Title.
case_studies[].summary	string	Short summary.
case_studies[].year	string	Project year.
case_studies[].location	string	Location.
case_studies[].url	string	Absolute URL to the case study page.
case_studies[].client_confirmed	boolean	Client confirmation present.
case_studies[].confirmed_partners	ApiCaseStudyPartner[]	Partners who confirmed on this case.
case_studies[].confirmed_partners[].name	string	Partner name.
case_studies[].confirmed_partners[].slug	string	Partner public slug.

Request

curl -sS "https://linken-tau.vercel.app/api/v1/companies/example-architecture/case-studies" \
  -H "Accept: application/json"

ResponseJSON

{
  "case_studies": [
    {
      "slug": "residence-berlin",
      "title": "Residence Berlin",
      "summary": "Private residence delivered with confirmed build and electrical partners.",
      "year": "2024",
      "location": "Berlin, Germany",
      "url": "https://linken-tau.vercel.app/c/example-architecture/case-studies/residence-berlin",
      "client_confirmed": true,
      "confirmed_partners": [
        { "name": "Example Build GmbH", "slug": "example-build" },
        { "name": "Example Elektro", "slug": "example-elektro" }
      ]
    }
  ],
  "count": 1
}

GET/api/v1/verify?domain={domain}

03.4

Verify (trust oracle)

One call to check a firm by website domain before you work with them. No API key. Unknown domains return found:false with HTTP 200.

Domain matching uses the same normalization as verification (exact host, www stripped). Only claimed companies are returned. Confirmed evidence only — never tokens or private fields.

Response fields

Field	Type	Description
found	boolean	Whether a claimed company matched the domain. false is still HTTP 200.
company	{ name, slug, profile_url } \| null	Matched firm when found.
verified	boolean	Domain verification flag.
verification_method	"email_domain" \| "dns_txt" \| "meta_tag" \| null	How the domain was verified; null if not verified.
verified_since	string \| null	ISO-8601 timestamp of domain verification.
trust_level	ApiTrustLevel \| null	Public trust level from confirmed evidence only.
stats	ApiCompanyStats \| null	Confirmed counts; null when not found.
assessment	ApiAssessment \| null	Null until ≥3 client assessment answers.
llm_md_url	string \| null	Markdown snapshot URL for LLMs.
api_url	string \| null	Canonical Public API company URL.

Request

curl -sS "https://linken-tau.vercel.app/api/v1/verify?domain=example.com" \
  -H "Accept: application/json"

ResponseJSON

{
  "found": true,
  "company": {
    "name": "Example Architecture",
    "slug": "example-architecture",
    "profile_url": "https://linken-tau.vercel.app/c/example-architecture"
  },
  "verified": true,
  "verification_method": "dns_txt",
  "verified_since": "2025-11-04T10:00:00.000Z",
  "trust_level": "established",
  "stats": {
    "confirmed_partners": 6,
    "confirmed_references": 4,
    "ongoing_references": 2,
    "confirmed_case_studies": 3
  },
  "assessment": {
    "would_work_again_yes": 9,
    "would_work_again_total": 10,
    "top_strengths": [
      { "key": "reliability", "label": "Reliability", "count": 8 }
    ]
  },
  "llm_md_url": "https://linken-tau.vercel.app/c/example-architecture/llm.md",
  "api_url": "https://linken-tau.vercel.app/api/v1/companies/example-architecture",
  "generated_at": "2026-07-19T18:00:00.000Z"
}

llms.txt & llm.md

Machine-readable entry points for AI agents that cite Hansala.

/llms.txt — site index: docs, API, profiles, trust model.
/c/{slug}/llm.md — markdown snapshot of a profile (same confirmed facts as the Public API). Linked from the HTML profile via rel="alternate".

Embeds

Drop an iframe on your site. Variants via ?variant=compact|badge|assessment|references and ?theme=light|dark. Links back with ?src=embed.

Prefer a visual configurator? Configure in your dashboard →

Badge

Compact verified mark. Default for existing embeds — no query param required.

Live preview

Snippet

<iframe src="https://linken-tau.vercel.app/embed/example-architecture" width="320" height="72" style="border:0" title="Verified on Hansala" loading="lazy"></iframe>

Assessment

Would-work-again rate and top strengths. Needs ≥3 client assessment answers on the profile.

Live preview

Snippet

<iframe src="https://linken-tau.vercel.app/embed/example-architecture?variant=assessment" width="320" height="120" style="border:0" title="Verified on Hansala" loading="lazy"></iframe>

References

Up to five confirmed client references. Empty profiles show a quiet fallback.

Live preview

Snippet

<iframe src="https://linken-tau.vercel.app/embed/example-architecture?variant=references" width="320" height="160" style="border:0" title="Verified on Hansala" loading="lazy"></iframe>

Agent API

Authenticated write surface for AI agents and integrations acting as your company. Create keys in Workspace → API.

What agents cannot do

Human confirmation is the product.

No confirm / accept / claim / respond endpoints — ever. An agent may build and invite; only a person with an email link may confirm.
No ownership transfer — blast radius stays human-only in the dashboard.
Keys are scoped to one company. Foreign company ids in the body are ignored or rejected. Public third-party reads use the Public API, not Agent routes.
Tokens for other parties, private_feedback, and foreign inquiries are never returned. Your own verify_token is available under verification:run.
Fields like verified, plan, slug, and claimed are not writable via PATCH /company.

Auth & scopes

Send Authorization: Bearer lk_…. The raw key is shown once at creation; we store only a SHA-256 hash. Revoke instantly from the dashboard.

Scope	Allows
read	Company, refs, cases, partnerships, inquiries, analytics, audit
content:write	Content, logo, profile fields, case-study partner tags
invites:send	Send confirmation / claim invites (never confirm)
team:manage	Team list, invites, remove members (accept via /join)
structure:manage	Groups, subsidiaries, parent proposals, leave
settings:write	Widget settings, embed catalog, accepting clients
inquiries:manage	Patch inquiry status
verification:run	Verify token/instructions + run checks

Presets in Workspace → API: Read only, Content manager, Full access. Rate limits: 120/min per key; invites 20/day per key.

Owner action → API endpoint

Everything an owner can click — except confirmations and ownership transfer — maps to Agent API.

Owner action	Endpoint	Scope
Edit profile fields	PATCH /company	content:write
Refresh / upload logo	POST /logo/refresh · PUT /logo	content:write
Add / edit / delete reference	POST\|PATCH\|DELETE /references	content:write
Send reference invite	POST /references/{id}/invite	invites:send
Case studies + partner tags	…/case-studies · …/partners	content:write
Client confirmation request	POST /client-confirmations	invites:send
Invite partner (ghost)	POST /partner-invites	invites:send
Verify domain / backlink	GET\|POST /verification…	verification:run
Team invite / remove	…/team…	team:manage
Group / subsidiary / hierarchy	…/group…	structure:manage
Widgets & logo wall	GET\|PATCH /widget-settings · GET /widgets	settings:write
Triage inquiries	GET /inquiries · PATCH /inquiries/{id}	read · inquiries:manage
Analytics / audit	GET /analytics · GET /audit-log	read

Agent setup script

Full lifecycle in six calls — create content, invite humans to confirm, configure the badge.

curl -sS -X PATCH "https://linken-tau.vercel.app/api/v1/agent/company" \
  -H "Authorization: Bearer lk_…" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"tagline":"Verified B2B network","city":"Berlin"}'

1. PATCH /company — tagline & city
2. POST /logo/refresh — pull logo from domain
3. POST /references ×3 — pending evidence
4. POST /references/{id}/invite — send confirms
5. GET /widgets — pick embed snippet
6. PATCH /widget-settings — logo wall exclusions

Endpoints

Base path https://linken-tau.vercel.app/api/v1/agent. Successes return { data: … }. Mutations are audit-logged. Team members expose opaque member_id (sha256 hex prefix) — never user_id.

GET/api/v1/agent/company

curl -sS -X GET "https://linken-tau.vercel.app/api/v1/agent/company" \
  -H "Authorization: Bearer lk_…" \
  -H "Accept: application/json"

POST/api/v1/agent/references

curl -sS -X POST "https://linken-tau.vercel.app/api/v1/agent/references" \
  -H "Authorization: Bearer lk_…" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"client_name":"CleanCo","service":"Office cleaning","started_year":"2024","ongoing":true}'

Errors

Failures use a consistent envelope. HTTP status matches the machine-readable code.

Status codes

200OK401unauthorized / invalid_key403insufficient_scope404not_found422invalid_request429rate_limited503service_unavailable500internal

Error body

Field	Type	Description
error.code	"not_found" \| "invalid_request" \| "internal"	Machine-readable code.
error.message	string	Human-readable message.

ExampleJSON

{
  "error": {
    "code": "not_found",
    "message": "Company not found."
  }
}

Versioning

A stable contract you can ship against.

Current

/api/v1/

Fields may be added. Never renamed, removed, or redefined.

Breaking changes

Ship under /api/v2/

Clients on v1 keep working. New major versions only when the meaning of a field must change.