API Reference

Identity

Generate and manage reusable marketing identities, share links, and personal writing plays.

Live keys only

Identity generation, management, share creation, and writing plays require a live bearer credential. Sandbox keys return PRODUCTION_KEY_REQUIRED. The tokenized shared identity read is intentionally public.

Generation is asynchronous

Website analysis can take several minutes. URL-only creation returns 202 Accepted; poll the returned status_url. If you already have the identity JSON, include it in the request to skip crawling and receive 201 Created immediately.

Get the Identity JSON Structure

GET/v1/identities/schema0 credits

Returns a JSON Schema Draft 2020-12 contract, required fields, and an example identity accepted by manual creation. companyName is the only required top-level identity field; all seven arrays declare their nested properties and required item fields, and brandVoice, geoFilter, and industryFilter are typed objects.

bash

curl -H "Authorization: Bearer ss_live_..." \
  "https://api.hillwinds.ai/v1/identities/schema"

Create an Identity Without Crawling

POST/v1/identities0 credits

Send url plus an identity object to save caller-authored positioning immediately. No crawl or AI generation job is started. The response is 201 Created and contains the complete persisted identity.

bash

curl -X POST -H "Authorization: Bearer ss_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "identity": {
      "companyName": "Acme",
      "industry": "Software",
      "brandVoice": {
        "tone": "Clear and direct",
        "avoid": ["em dashes", "guaranteed savings"]
      },
      "icps": [],
      "painPoints": [],
      "differentiators": [],
      "valueProps": [],
      "caseStudies": [],
      "proofPoints": [],
      "contentAngles": []
    }
  }' \
  "https://api.hillwinds.ai/v1/identities"

Start Identity Generation

POST/v1/identities0 credits

Parameter	Type	Description
`url`required	string (URL)	Company website used to generate the complete marketing identity.
`identity`	object	Omit this field to use website crawling. When supplied, crawling is skipped and the identity is saved immediately.
`outreach_context`	string	Optional context that should influence the generated positioning.

bash

curl -X POST -H "Authorization: Bearer ss_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "outreach_context": "Focus on benefits leaders at mid-market employers."
  }' \
  "https://api.hillwinds.ai/v1/identities"

json

{
  "ok": true,
  "data": {
    "job_id": "75d1a397-cccb-4d16-8a24-75831df47ab1",
    "status": "queued",
    "status_url": "https://api.hillwinds.ai/v1/identity-generation-jobs/75d1a397-cccb-4d16-8a24-75831df47ab1"
  },
  "meta": { "credits_charged": 0 }
}

Poll Generation Status

GET/v1/identity-generation-jobs/:job_id0 credits

Parameter	Type	Description
`wait_ms`	integer (0–5000)	Optional bounded long-poll duration in milliseconds.
`last_event_count`	integer	Optional last event_count observed. wait_ms also works without this cursor; the request returns when progress changes, the job finishes, or the wait expires.

Status is queued, running, completed, or failed. Every accepted job_id remains readable and reaches a terminal completed or failed state; a dropped or timed-out server job is represented as failed, not NOT_FOUND. A 404 is reserved for job IDs that were never issued to this user. Progress is non-decreasing for the lifetime of the job.

bash

curl -H "Authorization: Bearer ss_live_..." \
  "https://api.hillwinds.ai/v1/identity-generation-jobs/75d1a397-cccb-4d16-8a24-75831df47ab1?wait_ms=5000"

json

{
  "ok": true,
  "data": {
    "job_id": "75d1a397-cccb-4d16-8a24-75831df47ab1",
    "status": "completed",
    "progress": 100,
    "label": "Done",
    "event_count": 3,
    "events": [
      { "progress": 0, "label": "Queued...", "ts": 1783690000000 },
      { "progress": 35, "label": "Generating identity...", "ts": 1783690001000 },
      { "progress": 100, "label": "Done", "ts": 1783690060000 }
    ],
    "error": null,
    "identity": {
      "id": "b5855f72-e093-45bd-a657-7f58c8205917",
      "url": "example.com",
      "version": 1,
      "companyName": "Example",
      "brandVoice": {},
      "icps": [],
      "painPoints": [],
      "differentiators": [],
      "valueProps": [],
      "caseStudies": [],
      "contentAngles": []
    }
  },
  "meta": { "credits_charged": 0 }
}

List Identities

GET/v1/identities0 credits

Returns every saved identity version owned by the authenticated user, ordered by most recently updated. Rows contain id, url, version, versionName, companyName, industry, and timestamps. Version names are normalized with a · vN suffix, and updated_at can be used to distinguish versions in a selector.

bash

curl -H "Authorization: Bearer ss_live_..." \
  "https://api.hillwinds.ai/v1/identities"

Get Identity

GET/v1/identities/:id0 credits

Returns the complete saved identity JSON: brand voice, ICPs, pain points, differentiators, value propositions, case studies, proof points, content angles, geographic and industry filters, and generation usage metadata.

The response includes a strong ETag header. Preserve it and send it as If-Match when editing the identity, especially before replacing an array.

Edit Identity

PATCH/v1/identities/:id0 credits

Fields supplied in data are merged into the saved identity. A direct object of identity fields is also accepted. Arrays use full-replacement semantics rather than item-level merge semantics and require the current If-Match value; a missing precondition returns 428 PRECONDITION_REQUIRED, and a stale value returns 412 PRECONDITION_FAILED without applying the write.

Proof points are stored canonically in proofPoints. Legacy caseStudies entries marked entryType: "proof-point" are promoted and de-duplicated automatically, and an update that does not change the identity leaves updated_at unchanged.

bash

curl -X PATCH -H "Authorization: Bearer ss_live_..." \
  -H 'If-Match: "identity-etag-from-get"' \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "versionName": "Benefits leader positioning",
      "brandVoice": { "tone": "Clear, credible, and direct" }
    }
  }' \
  "https://api.hillwinds.ai/v1/identities/b5855f72-e093-45bd-a657-7f58c8205917"

Duplicate Identity

POST/v1/identities/:id/duplicate0 credits

Copies the identity into a new version owned by the authenticated user and returns the complete duplicate with its own identity ID. The returned versionName is normalized with the duplicate's current · vN suffix.

Delete Identity

DELETE/v1/identities/:id0 credits

Share links are invalidated

Deleting an identity also deletes its active share records. Existing tokenized links return NOT_FOUND.

POST/v1/identities/:id/share0 credits

Creates or returns the stable active link for this exact identity version. Treat the token as a secret: anyone with the URL can read the identity.

json

{
  "ok": true,
  "data": {
    "identity_id": "b5855f72-e093-45bd-a657-7f58c8205917",
    "token": "share_token_value",
    "url": "https://api.hillwinds.ai/v1/identity-shares/share_token_value",
    "status": "active",
    "created_at": "2026-07-10T14:30:00"
  },
  "meta": { "credits_charged": 0 }
}

Get a Shared Identity

GET/v1/identity-shares/:tokenPublic · 0 credits

Resolves an active share token to the complete identity JSON. No Authorization header is required. Unknown, inactive, or deleted shares return NOT_FOUND.

Writing Plays

GET/v1/writing-plays0 credits

Lists active personal writing plays owned by the authenticated user.

POST/v1/writing-plays0 credits

Adds one play or up to 100 plays atomically. Each requires name and body; subject is optional. Text is sanitized and source is manual.

A single-play request returns data as one object, matching CTA and subject creation. A request using { plays: [...] } returns data as an array and sets meta.bulk: true.

bash

curl -X POST -H "Authorization: Bearer ss_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "plays": [
      {
        "name": "Renewal timing",
        "subject": "Planning ahead for renewal",
        "body": "A concise message tailored to the prospect."
      },
      {
        "name": "Cost containment",
        "body": "A second reusable writing play."
      }
    ]
  }' \
  "https://api.hillwinds.ai/v1/writing-plays"

PATCH/v1/writing-plays/:id0 credits

Partially updates an owned active play. Send any non-empty subset of name, subject, and body. An empty string or null clears the subject; name and body cannot be empty.

bash

curl -X PATCH -H "Authorization: Bearer ss_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Corrected renewal timing" }' \
  "https://api.hillwinds.ai/v1/writing-plays/play_id"

DELETE/v1/writing-plays/:id0 credits

Soft-deletes an owned play so it no longer appears in lists. If the play is currently selected in writing preferences, the selection is cleared and the source returns to templates.

PreviousBrokers Next Filter Options

Need a key?

Keys are issued by our team, not a signup form. Book a 25-minute walkthrough and you'll leave with sandbox and live credentials.

Get access Explore the platform