Partner API

You are wiring a website to the ArchState Partner API v1.

Base URL: the ArchState origin. Production is https://archstate.archi. Use http://localhost:8080 only when the task says this is the development environment.
Key: environment variable ARCHSTATE_PARTNER_KEY. Never print, log, or commit the key.
Brand: this key is either personal or studio. Ask if that is not already stated. Do not call both brand routes.

Request: Authorization: Bearer <key>. Do not send cookies. Do not send Firebase Auth or App Check.

Personal key:
- GET /api/partner/v1/profile
- Then GET /api/partner/v1/project/{id} only for ids in data.projects

Studio key:
- GET /api/partner/v1/workspace
- Then GET /api/partner/v1/project/{id} only for ids in data.projects

Either key:
- POST /api/partner/v1/enquiry with JSON { name, email, message, subject? }. Optional honeypot field hp must be empty or omitted.
- Success is 201 { data: { id } }. Do not email the visitor from this API; ArchState notifies the owner.

The first GET response is the public brand plus a project list. Each row has id, title, headline, thumbnail_url, and the owning workspace (workspace_id, workspace_name, workspace_thumbnail_url). workspace_name is the owner label. workspace_thumbnail_url is the owner image. Those workspace fields may be absent on older rows. A row may also include status, categories, types, location ({ city, country }), floor_area, site_area, area_unit ("m2" or "ft2"), date_start, and date_end. Those listing fields are absent until that project is saved again. date_start and date_end are the project span. Use the list to render and filter. Load a project when a page needs the description, milestone dates, contributors, or section assets.

A personal profile may include location ({ city, country }). It is omitted when unset. A personal list is every public project that person is on, including work in other studios. Group or label those by workspace_id and workspace_name. A studio list is the public projects that studio owns; each row's workspace is that studio.

Success body is { data }. Errors are { message, code, status }.
- 401 INVALID_PARTNER_API_KEY: stop. The key is missing or unknown.
- 403 PARTNER_ORIGIN_NOT_ALLOWED: stop. The site hostname is not allowlisted. The port does not matter.
- 404 NOT_FOUND: this key cannot use that brand route.
- 404 PROJECT_NOT_FOUND: that project is not on this key's public list.
- 400 MISSING_REQUIRED_DATA: missing required fields or project URL with no id.
- 429 RATE_LIMIT_EXCEEDED: too many enquiries; wait and retry later.
Do not retry 401, 403, or 404.

Do not invent /api/partner/v1/projects or a second brand on this key.
Use image and file URLs exactly as returned.

Contract: the TypeScript below is the public shape. A field marked optional may be absent. Empty strings are omitted. Do not add fields.

type PartnerApiSuccess<T> = { data: T };
type PartnerApiError = { message: string; code: string; status: number };

type PartnerPublicContacts = {
  emails: Array<{ email: string; title?: string }>;
  phones: Array<{ country_code: string; phone: string; title?: string }>;
  social_media: Array<{
    platform: 'linkedin' | 'x' | 'instagram' | 'facebook' | 'youtube';
    username?: string;
    url: string;
  }>;
  websites: Array<{ title?: string; url: string }>;
};

type PartnerProjectSummary = {
  id: string;
  title: string;
  headline?: string;
  thumbnail_url?: string;
  workspace_id?: string;
  workspace_name?: string;
  workspace_thumbnail_url?: string;
  status?: string;
  categories?: string[];
  types?: string[];
  location?: { city?: string; country?: string };
  floor_area?: number;
  site_area?: number;
  area_unit?: 'm2' | 'ft2';
  date_start?: string;
  date_end?: string;
};

type PartnerProfile = {
  id: string;
  username: string;
  first_name: string;
  last_name: string;
  job_title?: string;
  company?: string;
  description?: string;
  photo_url?: string;
  location?: { city?: string; country?: string };
  contacts?: PartnerPublicContacts;
  projects: PartnerProjectSummary[];
};

type PartnerWorkspace = {
  id: string;
  type: 'personal' | 'studio';
  name: string;
  handle?: string;
  description?: string;
  thumbnail_url?: string;
  location?: { city?: string; country?: string };
  contacts?: PartnerPublicContacts;
  projects: PartnerProjectSummary[];
};

type PartnerAsset = {
  id: string;
  title?: string;
  alt?: string;
  description?: string;
  url?: string;
  thumbnail_url?: string;
  file_format?: string;
};

type PartnerContributor = {
  id: string;
  first_name: string;
  last_name: string;
  photo_url?: string;
  team_role?: string;
  team_section?: string;
};

type PartnerProjectDate = {
  id: string;
  title: string;
  type: string;
  date: string;
  is_primary?: boolean;
};

type PartnerProjectSection = {
  id: string;
  title: string;
  template_type: string;
  descriptions?: Array<{ title?: string; text: string }>;
  assets: PartnerAsset[];
};

type PartnerProjectGroup = {
  title: string;
  sections: PartnerProjectSection[];
};

type PartnerProject = {
  id: string;
  title: string;
  headline?: string;
  description?: string;
  thumbnail_url?: string;
  status?: string;
  categories?: string[];
  types?: string[];
  location?: { city?: string; country?: string };
  floor_area?: number;
  site_area?: number;
  area_unit?: 'm2' | 'ft2';
  date_start?: string;
  date_end?: string;
  dates?: PartnerProjectDate[];
  contributors: PartnerContributor[];
  groups: PartnerProjectGroup[];
};

type PartnerEnquiryBody = {
  name: string;
  email: string;
  message: string;
  subject?: string;
  hp?: string;
};

GET /api/partner/v1/profile → PartnerApiSuccess<PartnerProfile>
GET /api/partner/v1/workspace → PartnerApiSuccess<PartnerWorkspace>
GET /api/partner/v1/project/{id} → PartnerApiSuccess<PartnerProject>
POST /api/partner/v1/enquiry body → PartnerEnquiryBody
POST /api/partner/v1/enquiry success → PartnerApiSuccess<{ id: string }>
Errors → PartnerApiError