Italiano
Lingua
English Español Français Deutsch Italiano Attuale Português

Riferimento degli endpoint

Previous Next

Non ancora tradotta

Questa pagina non è ancora disponibile nella sua lingua, perciò viene mostrata in inglese.

Endpoint reference

Every endpoint of the Hi, Moose API, contract version 1.2.1, generated from the same OpenAPI file the API serves at api.himoose.com/v1/openapi.json. That file imports into Postman, Insomnia, Bruno and code generators.

All requests go to https://api.himoose.com/v1 and carry the key as a Bearer token, see Keys and authentication. Responses are JSON. Errors use the Problem Details format described in Errors and limits. Lists return data and nextCursor, see Reading data.

Permissions: Read visibility data is on every key. Manage tracking and Start runs are chosen when the key is created.

Contents

Account

Who the key belongs to and what it can read.

Describe the API key

GET /me

Permission: Read visibility data (every key)

Returns the key's label, permissions, expiry, the account plan and the project ids the key can read. A good first call to check a key.

Example

curl https://api.himoose.com/v1/me \
  -H "Authorization: Bearer hmk_live_..."

Responses

200 The key and its access.

Field Type Required Description
keyId string yes Short public id of the key, also shown in Settings.
label string yes The label given to the key when it was created.
scopes array of string: visibility:read, tracking:write, runs:execute yes The key's permissions.
createdAt string (RFC 3339 time) yes When the key was created.
expiresAt string (RFC 3339 time), or null yes When the key stops working, or null when it never expires.
account object yes The account the key belongs to.
account.plan string yes The plan code, for example free or premium.
projects array of string yes Project ids the key can read.

401 The key is missing, malformed, revoked or expired.

403 The account plan does not include the API, or the key lacks the scope.

429 The per-minute or per-day limit was reached.

Projects

Projects the key can read and what each one tracks.

List projects the key can read

GET /projects

Permission: Read visibility data (every key)

Lists the projects the key may read, newest first, with a summary of what each one tracks and when it last ran.

Parameters

Name In Type Required Description
cursor query string no The nextCursor value from the previous page. Opaque.
limit query integer no Rows per page. Default 50, at most 200. Default 50. At most 200.

Example

curl https://api.himoose.com/v1/projects \
  -H "Authorization: Bearer hmk_live_..."

Responses

200 A page of projects.

Field Type Required Description
data array of object yes The rows on this page.
data[].id string yes The project id used in every project endpoint.
data[].name string yes The project name as shown in Hi, Moose.
data[].websiteUrl string (URL), or null yes The site address the project tracks.
data[].visibility object yes A summary of what the project tracks and when it last ran.
data[].visibility.trackedPrompts integer yes How many prompts are tracked.
data[].visibility.engines array of string yes Ids of the engines the project tracks by default.
data[].visibility.latestRunAt string (RFC 3339 time), or null yes When the latest run finished, or null when no run has completed yet.
data[].visibility.firstAnswerDate string (YYYY-MM-DD), or null yes The first day with stored answers, or null.
data[].visibility.latestAnswerDate string (YYYY-MM-DD), or null yes The most recent day with stored answers, or null.
nextCursor string, or null yes Pass as cursor to get the next page. Null on the last page.

401 The key is missing, malformed, revoked or expired.

403 The account plan does not include the API, or the key lacks the scope.

429 The per-minute or per-day limit was reached.

Get one project

GET /projects/{projectId}

Permission: Read visibility data (every key)

Returns one project with its tracking summary.

Parameters

Name In Type Required Description
projectId path string yes The project id from the projects endpoint.

Example

curl https://api.himoose.com/v1/projects/PROJECT_ID \
  -H "Authorization: Bearer hmk_live_..."

Responses

200 The project.

Field Type Required Description
id string yes The project id used in every project endpoint.
name string yes The project name as shown in Hi, Moose.
websiteUrl string (URL), or null yes The site address the project tracks.
visibility object yes A summary of what the project tracks and when it last ran.
visibility.trackedPrompts integer yes How many prompts are tracked.
visibility.engines array of string yes Ids of the engines the project tracks by default.
visibility.latestRunAt string (RFC 3339 time), or null yes When the latest run finished, or null when no run has completed yet.
visibility.firstAnswerDate string (YYYY-MM-DD), or null yes The first day with stored answers, or null.
visibility.latestAnswerDate string (YYYY-MM-DD), or null yes The most recent day with stored answers, or null.

401 The key is missing, malformed, revoked or expired.

403 The account plan does not include the API, or the key lacks the scope.

404 No such resource, or the key cannot read it. The two cases are not told apart.

429 The per-minute or per-day limit was reached.

Setup

Engines, topics, prompts and tracked competitors for a project.

List the engines this project tracks

GET /projects/{projectId}/engines

Permission: Read visibility data (every key)

Engines are the AI answer engines Hi, Moose asks, such as ChatGPT, Gemini, Perplexity, Grok, Claude and Google AI Mode. The id is stable and is what the engine filter takes elsewhere.

Parameters

Name In Type Required Description
projectId path string yes The project id from the projects endpoint.

Example

curl https://api.himoose.com/v1/projects/PROJECT_ID/engines \
  -H "Authorization: Bearer hmk_live_..."

Responses

200 The engine list. Not paginated; there are at most a few dozen.

Field Type Required Description
data array of object yes The rows on this page.
data[].id string yes Stable engine id, for example chatgpt, gemini, perplexity, grok, claude, google-ai-mode. Local-fetch variants end in -local-fetch.
data[].label string yes Display name.
data[].tracked boolean yes Whether new runs ask this engine. Engines with stored answers but no longer tracked are listed with false.

401 The key is missing, malformed, revoked or expired.

403 The account plan does not include the API, or the key lacks the scope.

404 No such resource, or the key cannot read it. The two cases are not told apart.

429 The per-minute or per-day limit was reached.

List the topics that group the tracked prompts

GET /projects/{projectId}/topics

Permission: Read visibility data (every key)

Lists the topics that group the tracked prompts, with a prompt count each. Topic ids are the values to pass as topicId.

Parameters

Name In Type Required Description
projectId path string yes The project id from the projects endpoint.
cursor query string no The nextCursor value from the previous page. Opaque.
limit query integer no Rows per page. Default 50, at most 200. Default 50. At most 200.

Example

curl https://api.himoose.com/v1/projects/PROJECT_ID/topics \
  -H "Authorization: Bearer hmk_live_..."

Responses

200 A page of topics.

Field Type Required Description
data array of object yes The rows on this page.
data[].id string yes The topic id to pass as topicId in filters and on prompts.
data[].label string yes The topic name as shown in Hi, Moose.
data[].promptCount integer yes How many tracked prompts belong to this topic.
nextCursor string, or null yes Pass as cursor to get the next page. Null on the last page.

401 The key is missing, malformed, revoked or expired.

403 The account plan does not include the API, or the key lacks the scope.

404 No such resource, or the key cannot read it. The two cases are not told apart.

429 The per-minute or per-day limit was reached.

List the tracked prompts

GET /projects/{projectId}/prompts

Permission: Read visibility data (every key)

Lists the tracked prompts, newest first, with their topics, engines and status.

Parameters

Name In Type Required Description
projectId path string yes The project id from the projects endpoint.
topicId query string no Only prompts or answers in this topic. Ids come from the topics endpoint.
status query string: active, paused no Only prompts with this status. Default is all.
cursor query string no The nextCursor value from the previous page. Opaque.
limit query integer no Rows per page. Default 50, at most 200. Default 50. At most 200.

Example

curl https://api.himoose.com/v1/projects/PROJECT_ID/prompts \
  -H "Authorization: Bearer hmk_live_..."

Responses

200 A page of prompts.

Field Type Required Description
data array of object yes The rows on this page.
data[].id string yes The prompt id used in the prompt endpoints and the promptId filter.
data[].text string yes The question the engines are asked.
data[].topicIds array of string yes Ids of the topics this prompt belongs to.
data[].engineIds array of string yes Ids of the engines that run this prompt. Empty means the prompt uses no engine and is skipped in runs.
data[].status string: active, paused yes active prompts run on schedule; paused prompts are kept but not run.
data[].createdAt string (RFC 3339 time), or null yes When the prompt was added.
nextCursor string, or null yes Pass as cursor to get the next page. Null on the last page.

400 A parameter is missing or malformed.

401 The key is missing, malformed, revoked or expired.

403 The account plan does not include the API, or the key lacks the scope.

404 No such resource, or the key cannot read it. The two cases are not told apart.

429 The per-minute or per-day limit was reached.

List the tracked competitors

GET /projects/{projectId}/competitors

Permission: Read visibility data (every key)

The competitor brands Hi, Moose looks for in every answer. Competitor stats use these names.

Parameters

Name In Type Required Description
projectId path string yes The project id from the projects endpoint.

Example

curl https://api.himoose.com/v1/projects/PROJECT_ID/competitors \
  -H "Authorization: Bearer hmk_live_..."

Responses

200 The competitor list. Not paginated; at most 50.

Field Type Required Description
data array of object yes The rows on this page.
data[].name string yes The competitor brand name as it is matched in answers.
data[].domains array of string yes Domains that count as this competitor being cited.

401 The key is missing, malformed, revoked or expired.

403 The account plan does not include the API, or the key lacks the scope.

404 No such resource, or the key cannot read it. The two cases are not told apart.

429 The per-minute or per-day limit was reached.

Results

Runs and the stored answers from each engine.

List visibility runs

GET /projects/{projectId}/runs

Permission: Read visibility data (every key)

A run is one pass over the tracked prompts on the tracked engines. Newest first.

Parameters

Name In Type Required Description
projectId path string yes The project id from the projects endpoint.
from query string (YYYY-MM-DD) no First day to include, YYYY-MM-DD, UTC.
to query string (YYYY-MM-DD) no Last day to include, YYYY-MM-DD, UTC. Defaults to today.
status query string: completed, running, failed, canceled no Only runs with this status.
cursor query string no The nextCursor value from the previous page. Opaque.
limit query integer no Rows per page. Default 50, at most 200. Default 50. At most 200.

Example

curl https://api.himoose.com/v1/projects/PROJECT_ID/runs \
  -H "Authorization: Bearer hmk_live_..."

Responses

200 A page of runs.

Field Type Required Description
data array of object yes The rows on this page.
data[].id string yes The run id to pass as runId on the answers endpoint.
data[].status string: completed, running, failed, canceled yes completed runs have all their answers stored. running runs are still collecting. failed and canceled runs may have partial answers.
data[].trigger string: scheduled, manual yes scheduled when the project schedule started it, manual when a person or the API started it.
data[].startedAt string (RFC 3339 time), or null yes When the run started.
data[].completedAt string (RFC 3339 time), or null yes When the run finished, or null while it is running.
data[].promptCount integer yes How many prompts the run covered.
data[].answerCount integer yes How many answers the run stored.
nextCursor string, or null yes Pass as cursor to get the next page. Null on the last page.

400 A parameter is missing or malformed.

401 The key is missing, malformed, revoked or expired.

403 The account plan does not include the API, or the key lacks the scope.

404 No such resource, or the key cannot read it. The two cases are not told apart.

429 The per-minute or per-day limit was reached.

List stored answers

GET /projects/{projectId}/answers

Permission: Read visibility data (every key)

One answer is one engine's reply to one prompt on one date. Newest first. This list carries the excerpt, the mention and citation flags, the position, the sentiment, the competitors seen and the source URLs. The full answer text is on the detail endpoint. Date range defaults to the last 30 days. The widest range per request is 366 days.

Parameters

Name In Type Required Description
projectId path string yes The project id from the projects endpoint.
from query string (YYYY-MM-DD) no First day to include, YYYY-MM-DD, UTC.
to query string (YYYY-MM-DD) no Last day to include, YYYY-MM-DD, UTC. Defaults to today.
engine query array of string no Only this engine. Repeat the parameter for several engines. Values come from the engines endpoint.
topicId query string no Only prompts or answers in this topic. Ids come from the topics endpoint.
promptId query string no Only answers to this prompt. Ids come from the prompts endpoint.
runId query string no Only answers from this run. Ids come from the runs endpoint or a webhook event.
mentioned query boolean no Only answers where the brand was, or was not, mentioned.
cited query boolean no Only answers where the brand's site was, or was not, cited.
cursor query string no The nextCursor value from the previous page. Opaque.
limit query integer no Rows per page. Default 50, at most 200. Default 50. At most 200.

Example

curl https://api.himoose.com/v1/projects/PROJECT_ID/answers \
  -H "Authorization: Bearer hmk_live_..."

Responses

200 A page of answers.

Field Type Required Description
data array of object yes The rows on this page.
data[].id string yes The answer id to pass to the answer detail endpoint.
data[].runId string, or null yes The run this answer came from, or null for answers imported from outside a run.
data[].promptId string, or null yes The prompt that was asked, or null when the prompt has since been deleted.
data[].promptText string yes The prompt text at the time it was asked.
data[].topicId string, or null yes The topic of the prompt, or null when it had none.
data[].topicLabel string, or null yes The topic name, or null.
data[].engineId string yes The engine that answered. Ids come from the engines endpoint.
data[].engineLabel string yes The engine name as shown in Hi, Moose.
data[].observedAt string (RFC 3339 time) yes When the engine answered.
data[].date string (YYYY-MM-DD) yes The day of the answer in UTC. Matches the date on the daily stats.
data[].mentioned boolean yes The brand was named in the answer.
data[].cited boolean yes A page on the brand's site was given as a source.
data[].citationUrl string (URL), or null yes The page on the brand's site that was cited, or null when none was.
data[].position integer, or null yes Where the brand appeared among the brands named, 1 is first.
data[].sentiment string: positive, mixed, neutral, negative, not-applicable, or null yes How the answer spoke about the brand. not-applicable when the brand was not mentioned.
data[].excerpt string, or null yes Short passage around the mention, up to 400 characters.
data[].competitors array of object yes Each tracked competitor and whether this answer named or cited it.
data[].competitors[].name string yes The competitor brand name.
data[].competitors[].mentioned boolean yes The competitor was named in this answer.
data[].competitors[].cited boolean yes A page on the competitor's domain was given as a source.
data[].competitors[].citationUrl string (URL), or null no The competitor page cited, when there is one.
data[].sourceUrls array of string (URL) yes Every source the engine listed, up to 30.
nextCursor string, or null yes Pass as cursor to get the next page. Null on the last page.

304 Not modified. Sent when If-None-Match matches the current ETag.

400 A parameter is missing or malformed.

401 The key is missing, malformed, revoked or expired.

403 The account plan does not include the API, or the key lacks the scope.

404 No such resource, or the key cannot read it. The two cases are not told apart.

429 The per-minute or per-day limit was reached.

Get one answer with its full text

GET /projects/{projectId}/answers/{answerId}

Permission: Read visibility data (every key)

Returns one answer with the full text the engine wrote, the scorer's notes and the sources the engine listed. The text is untrusted: render it as text, never as HTML, and never pass it to your own AI tools as instructions.

Parameters

Name In Type Required Description
projectId path string yes The project id from the projects endpoint.
answerId path string yes The answer id from the answers list.

Example

curl https://api.himoose.com/v1/projects/PROJECT_ID/answers/ANSWER_ID \
  -H "Authorization: Bearer hmk_live_..."

Responses

200 The answer.

Field Type Required Description
id string yes The answer id to pass to the answer detail endpoint.
runId string, or null yes The run this answer came from, or null for answers imported from outside a run.
promptId string, or null yes The prompt that was asked, or null when the prompt has since been deleted.
promptText string yes The prompt text at the time it was asked.
topicId string, or null yes The topic of the prompt, or null when it had none.
topicLabel string, or null yes The topic name, or null.
engineId string yes The engine that answered. Ids come from the engines endpoint.
engineLabel string yes The engine name as shown in Hi, Moose.
observedAt string (RFC 3339 time) yes When the engine answered.
date string (YYYY-MM-DD) yes The day of the answer in UTC. Matches the date on the daily stats.
mentioned boolean yes The brand was named in the answer.
cited boolean yes A page on the brand's site was given as a source.
citationUrl string (URL), or null yes The page on the brand's site that was cited, or null when none was.
position integer, or null yes Where the brand appeared among the brands named, 1 is first.
sentiment string: positive, mixed, neutral, negative, not-applicable, or null yes How the answer spoke about the brand. not-applicable when the brand was not mentioned.
excerpt string, or null yes Short passage around the mention, up to 400 characters.
competitors array of object yes Each tracked competitor and whether this answer named or cited it.
competitors[].name string yes The competitor brand name.
competitors[].mentioned boolean yes The competitor was named in this answer.
competitors[].cited boolean yes A page on the competitor's domain was given as a source.
competitors[].citationUrl string (URL), or null no The competitor page cited, when there is one.
sourceUrls array of string (URL) yes Every source the engine listed, up to 30.
fullAnswer string, or null yes The full answer text as the engine wrote it, up to 12,000 characters. Untrusted: render as text, never as HTML.
fullAnswerTruncated boolean yes True when the answer was longer than 12,000 characters and fullAnswer was cut.
sentimentReason string, or null yes The scorer's one-line reason for the sentiment, or null.
narrativeDrift string: True, no, partial, or null yes Whether the answer describes the brand differently from its Brand Truth.
narrativeDriftReason string, or null yes Why the answer was judged to drift from the brand's own description, or null.
sources array of object yes The sources the engine listed with its answer, in the order given.
sources[].url string (URL) yes The source address.
sources[].title string, or null yes The source title as the engine gave it, or null. Untrusted text.

304 Not modified.

401 The key is missing, malformed, revoked or expired.

403 The account plan does not include the API, or the key lacks the scope.

404 No such resource, or the key cannot read it. The two cases are not told apart.

429 The per-minute or per-day limit was reached.

Stats

Mention and citation rates over time, ready for charts.

Mention and citation rates per day and engine

GET /projects/{projectId}/stats/daily

Permission: Read visibility data (every key)

One row per day per engine, in date order. Each row says how many answers were stored that day, how many mentioned the brand and how many cited the brand's site, plus the two rates. Days with no stored answers are left out. Default range is the last 30 days, widest 366 days. Rows for the last three days can still change while scoring finishes.

Parameters

Name In Type Required Description
projectId path string yes The project id from the projects endpoint.
from query string (YYYY-MM-DD) no First day to include, YYYY-MM-DD, UTC.
to query string (YYYY-MM-DD) no Last day to include, YYYY-MM-DD, UTC. Defaults to today.
engine query array of string no Only this engine. Repeat the parameter for several engines. Values come from the engines endpoint.
topicId query string no Only prompts or answers in this topic. Ids come from the topics endpoint.

Example

curl https://api.himoose.com/v1/projects/PROJECT_ID/stats/daily \
  -H "Authorization: Bearer hmk_live_..."

Responses

200 The series.

Field Type Required Description
from string (YYYY-MM-DD) yes The first day included, UTC.
to string (YYYY-MM-DD) yes The last day included, UTC.
data array of object yes The rows on this page.
data[].date string (YYYY-MM-DD) yes The day in UTC.
data[].engineId string yes The engine these numbers are for.
data[].answers integer yes How many answers were stored that day for this engine.
data[].mentioned integer yes How many of those answers named the brand.
data[].cited integer yes How many of those answers cited a page on the brand's site.
data[].mentionRate number, or null yes mentioned divided by answers, 0 to 1.
data[].citationRate number, or null yes cited divided by answers, 0 to 1.
incompleteDays integer yes Days in the range whose summary was not ready yet. Zero means the series is complete. When above zero, call again in a few seconds.

400 A parameter is missing or malformed.

401 The key is missing, malformed, revoked or expired.

403 The account plan does not include the API, or the key lacks the scope.

404 No such resource, or the key cannot read it. The two cases are not told apart.

429 The per-minute or per-day limit was reached.

Share of voice for the brand and its tracked competitors

GET /projects/{projectId}/stats/competitors

Permission: Read visibility data (every key)

For the range, one row per brand name (the project's own brand first, then each tracked competitor) with how many answers mentioned it, how many cited it, and the rates. With engine given, only that engine's answers count.

Parameters

Name In Type Required Description
projectId path string yes The project id from the projects endpoint.
from query string (YYYY-MM-DD) no First day to include, YYYY-MM-DD, UTC.
to query string (YYYY-MM-DD) no Last day to include, YYYY-MM-DD, UTC. Defaults to today.
engine query array of string no Only this engine. Repeat the parameter for several engines. Values come from the engines endpoint.

Example

curl https://api.himoose.com/v1/projects/PROJECT_ID/stats/competitors \
  -H "Authorization: Bearer hmk_live_..."

Responses

200 The share of voice table.

Field Type Required Description
from string (YYYY-MM-DD) yes The first day included, UTC.
to string (YYYY-MM-DD) yes The last day included, UTC.
answers integer yes Answers counted in the range.
data array of object yes The rows on this page.
data[].name string yes The brand or competitor name.
data[].isOwnBrand boolean yes True on the row for the project's own brand.
data[].mentioned integer yes How many answers in the range named this brand.
data[].cited integer yes How many answers in the range cited this brand's site.
data[].mentionRate number, or null yes mentioned divided by all answers in the range, 0 to 1.
data[].citationRate number, or null yes cited divided by all answers in the range, 0 to 1.

400 A parameter is missing or malformed.

401 The key is missing, malformed, revoked or expired.

403 The account plan does not include the API, or the key lacks the scope.

404 No such resource, or the key cannot read it. The two cases are not told apart.

429 The per-minute or per-day limit was reached.

Tracking

Create projects and manage what Hi, Moose tracks. Needs the tracking:write permission.

Create a project

POST /projects

Permission: Manage tracking

Creates a project with a name and site address. The site crawl is not started; the host computer turns on the weekly scheduled crawl so it happens later. If another project on the account has a host device, the new project uses the same one. Brand Truth is not required.

Request body

Field Type Required Description
name string yes The project name, shown in Hi, Moose. At most 120 characters.
websiteUrl string (URL) yes The site address to track, with https.
brandTerms array of string no Other names the brand goes by, counted as mentions. At most 20 items.
brandDomains array of string no Other domains that count as the brand being cited. At most 20 items.

Example

curl -X POST https://api.himoose.com/v1/projects \
  -H "Authorization: Bearer hmk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme", "websiteUrl": "https://example.com/page"}'

Responses

201 The new project.

Field Type Required Description
id string yes The project id used in every project endpoint.
name string yes The project name as shown in Hi, Moose.
websiteUrl string (URL), or null yes The site address the project tracks.
visibility object yes A summary of what the project tracks and when it last ran.
visibility.trackedPrompts integer yes How many prompts are tracked.
visibility.engines array of string yes Ids of the engines the project tracks by default.
visibility.latestRunAt string (RFC 3339 time), or null yes When the latest run finished, or null when no run has completed yet.
visibility.firstAnswerDate string (YYYY-MM-DD), or null yes The first day with stored answers, or null.
visibility.latestAnswerDate string (YYYY-MM-DD), or null yes The most recent day with stored answers, or null.
host object no The project's host computer.
host.configured boolean yes A host device is chosen for the project in Hi, Moose under Settings, Hi, Moose MCP.
host.online boolean yes True when the host computer has checked in within the last few minutes.
host.deviceLabel string, or null yes The name of the host computer as shown in Hi, Moose.
host.lastSeenAt string (RFC 3339 time), or null yes When the host computer last checked in, or null when it never has.
warning string, or null no A note about something to finish in Hi, Moose, for example that no host computer could be copied from another project. Null when there is nothing to do.
brandTerms array of string no Other names the brand goes by, counted as mentions.
brandDomains array of string no Other domains that count as the brand being cited.

400 A parameter is missing or malformed.

401 The key is missing, malformed, revoked or expired.

403 The account plan does not include the API, or the key lacks the scope.

404 No such resource, or the key cannot read it. The two cases are not told apart.

409 The request is valid but cannot be done right now. The code says why.

429 The per-minute or per-day limit was reached.

Change a project name, site address, brand terms or domains

PATCH /projects/{projectId}

Permission: Manage tracking

Changes only the fields sent. Brand terms and brand domains replace the whole list when sent. The site crawl is not touched.

Parameters

Name In Type Required Description
projectId path string yes The project id from the projects endpoint.

Request body

Field Type Required Description
name string no A new project name.
websiteUrl string (URL) no A new site address, with https.
brandTerms array of string no Replaces the list of other names the brand goes by.
brandDomains array of string no Replaces the list of other domains that count as the brand being cited.

Example

curl -X PATCH https://api.himoose.com/v1/projects/PROJECT_ID \
  -H "Authorization: Bearer hmk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme"}'

Responses

200 The resource.

Field Type Required Description
id string yes The project id used in every project endpoint.
name string yes The project name as shown in Hi, Moose.
websiteUrl string (URL), or null yes The site address the project tracks.
visibility object yes A summary of what the project tracks and when it last ran.
visibility.trackedPrompts integer yes How many prompts are tracked.
visibility.engines array of string yes Ids of the engines the project tracks by default.
visibility.latestRunAt string (RFC 3339 time), or null yes When the latest run finished, or null when no run has completed yet.
visibility.firstAnswerDate string (YYYY-MM-DD), or null yes The first day with stored answers, or null.
visibility.latestAnswerDate string (YYYY-MM-DD), or null yes The most recent day with stored answers, or null.
host object no The project's host computer.
host.configured boolean yes A host device is chosen for the project in Hi, Moose under Settings, Hi, Moose MCP.
host.online boolean yes True when the host computer has checked in within the last few minutes.
host.deviceLabel string, or null yes The name of the host computer as shown in Hi, Moose.
host.lastSeenAt string (RFC 3339 time), or null yes When the host computer last checked in, or null when it never has.
warning string, or null no A note about something to finish in Hi, Moose, for example that no host computer could be copied from another project. Null when there is nothing to do.
brandTerms array of string no Other names the brand goes by, counted as mentions.
brandDomains array of string no Other domains that count as the brand being cited.

400 A parameter is missing or malformed.

401 The key is missing, malformed, revoked or expired.

403 The account plan does not include the API, or the key lacks the scope.

404 No such resource, or the key cannot read it. The two cases are not told apart.

409 The request is valid but cannot be done right now. The code says why.

429 The per-minute or per-day limit was reached.

Add a tracked prompt

POST /projects/{projectId}/prompts

Permission: Manage tracking

Engine ids default to the project tracking engines. Duplicate text is refused with 409.

Parameters

Name In Type Required Description
projectId path string yes The project id from the projects endpoint.

Request body

Field Type Required Description
text string yes The question to ask the engines. At most 500 characters.
topicIds array of string no Topic ids from the topics endpoint. A new id creates the topic. At most 20 items.
engineIds array of string no Defaults to the project tracking engines.

Example

curl -X POST https://api.himoose.com/v1/projects/PROJECT_ID/prompts \
  -H "Authorization: Bearer hmk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text": "What are the best SAST tools?", "topicIds": ["string"], "engineIds": ["string"]}'

Responses

201 The new prompt.

Field Type Required Description
id string yes The prompt id used in the prompt endpoints and the promptId filter.
text string yes The question the engines are asked.
topicIds array of string yes Ids of the topics this prompt belongs to.
engineIds array of string yes Ids of the engines that run this prompt. Empty means the prompt uses no engine and is skipped in runs.
status string: active, paused yes active prompts run on schedule; paused prompts are kept but not run.
createdAt string (RFC 3339 time), or null yes When the prompt was added.

400 A parameter is missing or malformed.

401 The key is missing, malformed, revoked or expired.

403 The account plan does not include the API, or the key lacks the scope.

404 No such resource, or the key cannot read it. The two cases are not told apart.

409 The request is valid but cannot be done right now. The code says why.

429 The per-minute or per-day limit was reached.

Replace the tracked competitor list

PUT /projects/{projectId}/competitors

Permission: Manage tracking

Replaces the whole list. At most 50. Names are matched case-insensitively.

Parameters

Name In Type Required Description
projectId path string yes The project id from the projects endpoint.

Request body

The body is a JSON array. At most 50 items. Each item:

Field Type Required Description
name string yes The competitor brand name as it should be matched in answers. At most 120 characters.
domain string, or null no The competitor's site, so citations of it are counted. Optional.

Example

curl -X PUT https://api.himoose.com/v1/projects/PROJECT_ID/competitors \
  -H "Authorization: Bearer hmk_live_..." \
  -H "Content-Type: application/json" \
  -d '[{"name": "Acme", "domain": "example.com"}]'

Responses

200 The saved list.

Field Type Required Description
data array of object yes The rows on this page.
data[].name string yes The competitor brand name as it is matched in answers.
data[].domains array of string yes Domains that count as this competitor being cited.

400 A parameter is missing or malformed.

401 The key is missing, malformed, revoked or expired.

403 The account plan does not include the API, or the key lacks the scope.

404 No such resource, or the key cannot read it. The two cases are not told apart.

409 The request is valid but cannot be done right now. The code says why.

429 The per-minute or per-day limit was reached.

What this project can do on its plan

GET /projects/{projectId}/capabilities

Permission: Read visibility data (every key)

Allowed engines and cadences, prompt and project limits, remaining allowance with the estimated cost of one run, the host computer status, and whether a run can start right now.

Parameters

Name In Type Required Description
projectId path string yes The project id from the projects endpoint.

Example

curl https://api.himoose.com/v1/projects/PROJECT_ID/capabilities \
  -H "Authorization: Bearer hmk_live_..."

Responses

200 The resource.

Field Type Required Description
plan string yes The account plan code.
accessMode string: managed, byok-local yes managed means Hi, Moose runs the cloud engines and tracking settings live in the cloud. byok-local means the account brings its own keys and tracking settings live on the host computer.
engines array of object yes Every engine the plan allows, tracked or not.
engines[].id string no The engine id to use in engineIds and filters.
engines[].label string no The engine name as shown in Hi, Moose.
engines[].runsOn string: cloud, host no cloud engines run in the cloud; host engines run on the host computer through a browser.
cadences array of string yes The schedule cadences the plan allows.
limits object yes The plan's limits. Writes over a limit answer 409 plan_limit.
limits.maxPrompts integer, or null no The most prompts one project may track.
limits.maxProjects integer, or null no The most projects the account may have.
limits.maxCompetitors integer no The most competitors one project may track.
limits.maxSamplesPerPrompt integer no The highest samplesPerPrompt the plan allows.
limits.runRequestsPerDay integer no How many run requests one project may make per day through the API.
allowance object, or null yes Null on bring-your-own-key plans.
allowance.remainingUnits integer, or null no Allowance units left in the current period, or null when the plan has no period.
allowance.prepaidCreditsRemaining integer no Prepaid credit units that are spent after the period allowance runs out.
allowance.periodEndsAt string (RFC 3339 time), or null no When the current allowance period resets, or null.
allowance.estimatedUnitsPerRun integer no The estimated cost of one run with one sample per prompt, from the current prompts and engines.
tracking object yes The project's current tracking settings.
tracking.engineIds array of string no The default engines for new prompts.
tracking.cadence string no How often the schedule runs.
tracking.timeOfDay string no When the scheduled run starts, HH:MM in the project timezone.
tracking.weeklyDay string no The day a weekly schedule runs on.
tracking.timezone string no The IANA timezone the schedule uses.
tracking.samplesPerPrompt integer no How many times each prompt is asked per engine in a run.
tracking.promptCount integer no How many prompts the project tracks.
tracking.writable boolean no False on bring-your-own-key plans, where tracking settings live on the host computer.
host object yes The project's host computer, or null when none is chosen.
host.configured boolean yes A host device is chosen for the project in Hi, Moose under Settings, Hi, Moose MCP.
host.online boolean yes True when the host computer has checked in within the last few minutes.
host.deviceLabel string, or null yes The name of the host computer as shown in Hi, Moose.
host.lastSeenAt string (RFC 3339 time), or null yes When the host computer last checked in, or null when it never has.
host.required boolean no True when any tracked engine is a local-fetch engine or the plan is bring-your-own-key.
runs object yes Whether a run can start right now and why not.
runs.canStartCloudRun boolean no True when a cloud run could start now: engines, allowance and no active request.
runs.canStartHostRun boolean no True when a host run could start now: a host computer is chosen and no request is active.
runs.hostOnline boolean no True when the host computer is checked in.
runs.activeRequestId string, or null no The id of the run request that is queued, waiting or running, or null.
runs.usedToday integer no How many run requests the project has made today.

400 A parameter is missing or malformed.

401 The key is missing, malformed, revoked or expired.

403 The account plan does not include the API, or the key lacks the scope.

404 No such resource, or the key cannot read it. The two cases are not told apart.

409 The request is valid but cannot be done right now. The code says why.

429 The per-minute or per-day limit was reached.

Change a prompt

PATCH /projects/{projectId}/prompts/{promptId}

Permission: Manage tracking

Only the fields sent change. status can only be active; delete a prompt to stop tracking it.

Parameters

Name In Type Required Description
projectId path string yes The project id from the projects endpoint.
promptId path string yes The prompt id from the prompts list.

Request body

Field Type Required Description
text string no New text for the prompt. At most 500 characters.
topicIds array of string no Replaces the prompt's topics.
engineIds array of string no Replaces the engines that run this prompt.
status string: active no Send active to resume a prompt that was paused in Hi, Moose.

Example

curl -X PATCH https://api.himoose.com/v1/projects/PROJECT_ID/prompts/PROMPT_ID \
  -H "Authorization: Bearer hmk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text": "What are the best SAST tools?"}'

Responses

200 The resource.

Field Type Required Description
id string yes The prompt id used in the prompt endpoints and the promptId filter.
text string yes The question the engines are asked.
topicIds array of string yes Ids of the topics this prompt belongs to.
engineIds array of string yes Ids of the engines that run this prompt. Empty means the prompt uses no engine and is skipped in runs.
status string: active, paused yes active prompts run on schedule; paused prompts are kept but not run.
createdAt string (RFC 3339 time), or null yes When the prompt was added.

400 A parameter is missing or malformed.

401 The key is missing, malformed, revoked or expired.

403 The account plan does not include the API, or the key lacks the scope.

404 No such resource, or the key cannot read it. The two cases are not told apart.

409 The request is valid but cannot be done right now. The code says why.

429 The per-minute or per-day limit was reached.

Stop tracking a prompt

DELETE /projects/{projectId}/prompts/{promptId}

Permission: Manage tracking

Removes the prompt from tracking. Stored answers for it are kept and stay readable on the answers endpoint.

Parameters

Name In Type Required Description
projectId path string yes The project id from the projects endpoint.
promptId path string yes The prompt id from the prompts list.

Example

curl -X DELETE https://api.himoose.com/v1/projects/PROJECT_ID/prompts/PROMPT_ID \
  -H "Authorization: Bearer hmk_live_..."

Responses

200 Deleted.

Field Type Required Description
deleted boolean no True when the item was removed.

400 A parameter is missing or malformed.

401 The key is missing, malformed, revoked or expired.

403 The account plan does not include the API, or the key lacks the scope.

404 No such resource, or the key cannot read it. The two cases are not told apart.

409 The request is valid but cannot be done right now. The code says why.

429 The per-minute or per-day limit was reached.

Set engines, schedule and samples

PUT /projects/{projectId}/tracking

Permission: Manage tracking

Only the fields sent change. engineIds sets the default engines for new prompts. Existing prompts keep their own engines unless applyEnginesToPrompts is true. The host computer picks the new schedule up within a minute while it is open, or when it next opens.

Parameters

Name In Type Required Description
projectId path string yes The project id from the projects endpoint.

Request body

Field Type Required Description
engineIds array of string no The default engines for new prompts. Ids come from the capabilities endpoint.
applyEnginesToPrompts boolean no Send true to also set engineIds on every existing prompt. Left out or false, existing prompts keep their own engines and engineIds only becomes the default for new prompts. Default false.
cadence string: manual, daily, weekdays, weekly no How often the schedule runs. manual turns the schedule off.
timeOfDay string no When the scheduled run starts, as HH:MM in the project timezone.
weeklyDay string: monday, tuesday, wednesday, thursday, friday, saturday, sunday no The day a weekly schedule runs on.
timezone string no An IANA timezone name such as Europe/Berlin, used for timeOfDay.
samplesPerPrompt integer no How many times each prompt is asked per engine in a run. More samples cost more allowance.

Example

curl -X PUT https://api.himoose.com/v1/projects/PROJECT_ID/tracking \
  -H "Authorization: Bearer hmk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"engineIds": ["string"]}'

Responses

200 The resource.

Field Type Required Description
engineIds array of string yes The default engines for new prompts.
cadence string yes How often the schedule runs. manual means the schedule is off.
timeOfDay string yes When the scheduled run starts, as HH:MM in the project timezone.
weeklyDay string yes The day a weekly schedule runs on.
timezone string yes The IANA timezone the schedule uses.
samplesPerPrompt integer yes How many times each prompt is asked per engine in a run.
appliedToPrompts integer yes How many prompts had their engines updated.
host object yes The project's host computer.
host.configured boolean yes A host device is chosen for the project in Hi, Moose under Settings, Hi, Moose MCP.
host.online boolean yes True when the host computer has checked in within the last few minutes.
host.deviceLabel string, or null yes The name of the host computer as shown in Hi, Moose.
host.lastSeenAt string (RFC 3339 time), or null yes When the host computer last checked in, or null when it never has.

400 A parameter is missing or malformed.

401 The key is missing, malformed, revoked or expired.

403 The account plan does not include the API, or the key lacks the scope.

404 No such resource, or the key cannot read it. The two cases are not told apart.

409 The request is valid but cannot be done right now. The code says why.

429 The per-minute or per-day limit was reached.

Runs

Start visibility runs and follow them. Needs the runs:execute permission.

Start a visibility run

POST /projects/{projectId}/run-requests

Permission: Start runs

Checks the allowance first and refuses with 409 insufficient_allowance when the estimate is above the remaining balance. One request at a time per project, at most 24 per project per day. Projects whose tracked engines are all cloud engines run in the cloud at once. Any local-fetch engine means the run is handed to the host computer; if that computer is off the request is accepted with a warning and waits up to 24 hours. Send an Idempotency-Key header to make retries safe for 24 hours.

Parameters

Name In Type Required Description
projectId path string yes The project id from the projects endpoint.
Idempotency-Key header string no Any string up to 128 characters that identifies this attempt. A retry with the same key within 24 hours returns the earlier request instead of starting another run.

Request body (optional)

Field Type Required Description
samplesPerPrompt integer no How many times to ask each prompt per engine in this run. Defaults to 1 and may not exceed the plan limit. Default 1.

Example

curl -X POST https://api.himoose.com/v1/projects/PROJECT_ID/run-requests \
  -H "Authorization: Bearer hmk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"samplesPerPrompt": 1}' \
  -H "Idempotency-Key: nightly-2026-10-15"

Responses

200 Replayed from an earlier request with the same Idempotency-Key.

Field Type Required Description
id string yes The run request id. Poll it on the run request endpoint.
status string: waiting_for_host, queued, running, completed, failed, canceled yes waiting_for_host means the host computer is off; Hi, Moose waits up to 24 hours.
mode string: cloud, host yes cloud when the run runs in the cloud, host when it was handed to the host computer.
createdAt string (RFC 3339 time), or null yes When the request was made.
updatedAt string (RFC 3339 time), or null yes When the status last changed.
completedAt string (RFC 3339 time), or null yes When the run finished, or null until then.
runIds array of string yes Run ids to pass to the runs and answers endpoints once completed.
promptCount integer yes How many prompts the run covers.
estimatedUnits integer yes The estimated allowance cost. 0 for host-only runs and bring-your-own-key plans.
warning string, or null yes A note about the request, for example that the host computer is off, or null.
error object, or null yes Why the request failed, or null.
error.code string no A stable code such as host_unavailable.
error.message string no What happened, in plain words.
host object, or null yes The host computer handling the run, or null for cloud runs.
host.online boolean no True when the host computer is checked in.
host.lastSeenAt string (RFC 3339 time), or null no When the host computer last checked in, or null.
replayed boolean no Present and true when an Idempotency-Key matched an earlier request.

202 Accepted. Poll the Location header. Same fields as the 200 response.

400 A parameter is missing or malformed.

401 The key is missing, malformed, revoked or expired.

403 The account plan does not include the API, or the key lacks the scope.

404 No such resource, or the key cannot read it. The two cases are not told apart.

409 The request is valid but cannot be done right now. The code says why.

429 The per-minute or per-day limit was reached.

Recent run requests

GET /projects/{projectId}/run-requests

Permission: Read visibility data (every key)

Lists run requests made through the API, newest first, with their current status.

Parameters

Name In Type Required Description
projectId path string yes The project id from the projects endpoint.
limit query integer no Rows per page. Default 50, at most 200. Default 50. At most 200.

Example

curl https://api.himoose.com/v1/projects/PROJECT_ID/run-requests \
  -H "Authorization: Bearer hmk_live_..."

Responses

200 Newest first.

Field Type Required Description
data array of object yes The rows on this page.
data[].id string yes The run request id. Poll it on the run request endpoint.
data[].status string: waiting_for_host, queued, running, completed, failed, canceled yes waiting_for_host means the host computer is off; Hi, Moose waits up to 24 hours.
data[].mode string: cloud, host yes cloud when the run runs in the cloud, host when it was handed to the host computer.
data[].createdAt string (RFC 3339 time), or null yes When the request was made.
data[].updatedAt string (RFC 3339 time), or null yes When the status last changed.
data[].completedAt string (RFC 3339 time), or null yes When the run finished, or null until then.
data[].runIds array of string yes Run ids to pass to the runs and answers endpoints once completed.
data[].promptCount integer yes How many prompts the run covers.
data[].estimatedUnits integer yes The estimated allowance cost. 0 for host-only runs and bring-your-own-key plans.
data[].warning string, or null yes A note about the request, for example that the host computer is off, or null.
data[].error object, or null yes Why the request failed, or null.
data[].error.code string no A stable code such as host_unavailable.
data[].error.message string no What happened, in plain words.
data[].host object, or null yes The host computer handling the run, or null for cloud runs.
data[].host.online boolean no True when the host computer is checked in.
data[].host.lastSeenAt string (RFC 3339 time), or null no When the host computer last checked in, or null.
data[].replayed boolean no Present and true when an Idempotency-Key matched an earlier request.
nextCursor string, or null no Pass as cursor to get the next page. Null on the last page.

400 A parameter is missing or malformed.

401 The key is missing, malformed, revoked or expired.

403 The account plan does not include the API, or the key lacks the scope.

404 No such resource, or the key cannot read it. The two cases are not told apart.

409 The request is valid but cannot be done right now. The code says why.

429 The per-minute or per-day limit was reached.

Follow a run request

GET /projects/{projectId}/run-requests/{requestId}

Permission: Read visibility data (every key)

Returns one run request with its current status, run ids once completed, and the host computer state for host runs. Poll it about once a minute.

Parameters

Name In Type Required Description
projectId path string yes The project id from the projects endpoint.
requestId path string yes The run request id from the 202 response or its Location header.

Example

curl https://api.himoose.com/v1/projects/PROJECT_ID/run-requests/REQUEST_ID \
  -H "Authorization: Bearer hmk_live_..."

Responses

200 The resource.

Field Type Required Description
id string yes The run request id. Poll it on the run request endpoint.
status string: waiting_for_host, queued, running, completed, failed, canceled yes waiting_for_host means the host computer is off; Hi, Moose waits up to 24 hours.
mode string: cloud, host yes cloud when the run runs in the cloud, host when it was handed to the host computer.
createdAt string (RFC 3339 time), or null yes When the request was made.
updatedAt string (RFC 3339 time), or null yes When the status last changed.
completedAt string (RFC 3339 time), or null yes When the run finished, or null until then.
runIds array of string yes Run ids to pass to the runs and answers endpoints once completed.
promptCount integer yes How many prompts the run covers.
estimatedUnits integer yes The estimated allowance cost. 0 for host-only runs and bring-your-own-key plans.
warning string, or null yes A note about the request, for example that the host computer is off, or null.
error object, or null yes Why the request failed, or null.
error.code string no A stable code such as host_unavailable.
error.message string no What happened, in plain words.
host object, or null yes The host computer handling the run, or null for cloud runs.
host.online boolean no True when the host computer is checked in.
host.lastSeenAt string (RFC 3339 time), or null no When the host computer last checked in, or null.
replayed boolean no Present and true when an Idempotency-Key matched an earlier request.

400 A parameter is missing or malformed.

401 The key is missing, malformed, revoked or expired.

403 The account plan does not include the API, or the key lacks the scope.

404 No such resource, or the key cannot read it. The two cases are not told apart.

409 The request is valid but cannot be done right now. The code says why.

429 The per-minute or per-day limit was reached.

Webhooks

Get a signed HTTP call when a run finishes. Managing webhooks needs the tracking:write permission.

Register a webhook

POST /projects/{projectId}/webhooks

Permission: Manage tracking

Up to 5 per project. The url must be public https. The signing secret is returned once in this response and never again. Default events are run.completed and run.failed.

Parameters

Name In Type Required Description
projectId path string yes The project id from the projects endpoint.

Request body

Field Type Required Description
url string (URL) yes Public https endpoint. Private and local addresses are refused.
events array of string: run.completed, run.failed no Defaults to both.
description string no A note to tell webhooks apart in Settings. Optional. At most 120 characters.

Example

curl -X POST https://api.himoose.com/v1/projects/PROJECT_ID/webhooks \
  -H "Authorization: Bearer hmk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/page", "events": ["run.completed"], "description": "Nightly dashboard refresh"}'

Responses

201 The webhook with its signing secret.

Field Type Required Description
id string yes The webhook id used in the webhook endpoints.
url string (URL) yes The endpoint Hi, Moose posts events to.
events array of string yes The events this webhook receives.
description string, or null yes The note given when the webhook was registered, or null.
active boolean yes Turned off automatically after 20 consecutive failed deliveries. Delete and register again to resume.
createdAt string (RFC 3339 time), or null yes When the webhook was registered.
lastDeliveryAt string (RFC 3339 time), or null yes When the last delivery was attempted, or null before the first.
lastDeliveryStatus string: delivered, failed, or null yes How the last delivery ended, or null before the first.
consecutiveFailures integer yes Failed deliveries in a row. At 20 the webhook is turned off.
secret string yes Signing secret, starts with whsec_. Shown once.

400 A parameter is missing or malformed.

401 The key is missing, malformed, revoked or expired.

403 The account plan does not include the API, or the key lacks the scope.

404 No such resource, or the key cannot read it. The two cases are not told apart.

409 The request is valid but cannot be done right now. The code says why.

429 The per-minute or per-day limit was reached.

List webhooks

GET /projects/{projectId}/webhooks

Permission: Read visibility data (every key)

Lists the project's webhooks without their signing secrets.

Parameters

Name In Type Required Description
projectId path string yes The project id from the projects endpoint.

Example

curl https://api.himoose.com/v1/projects/PROJECT_ID/webhooks \
  -H "Authorization: Bearer hmk_live_..."

Responses

200 The webhooks, without secrets.

Field Type Required Description
data array of object yes The rows on this page.
data[].id string yes The webhook id used in the webhook endpoints.
data[].url string (URL) yes The endpoint Hi, Moose posts events to.
data[].events array of string yes The events this webhook receives.
data[].description string, or null yes The note given when the webhook was registered, or null.
data[].active boolean yes Turned off automatically after 20 consecutive failed deliveries. Delete and register again to resume.
data[].createdAt string (RFC 3339 time), or null yes When the webhook was registered.
data[].lastDeliveryAt string (RFC 3339 time), or null yes When the last delivery was attempted, or null before the first.
data[].lastDeliveryStatus string: delivered, failed, or null yes How the last delivery ended, or null before the first.
data[].consecutiveFailures integer yes Failed deliveries in a row. At 20 the webhook is turned off.

400 A parameter is missing or malformed.

401 The key is missing, malformed, revoked or expired.

403 The account plan does not include the API, or the key lacks the scope.

404 No such resource, or the key cannot read it. The two cases are not told apart.

409 The request is valid but cannot be done right now. The code says why.

429 The per-minute or per-day limit was reached.

Delete a webhook

DELETE /projects/{projectId}/webhooks/{webhookId}

Permission: Manage tracking

Removes the webhook. Pending deliveries are dropped.

Parameters

Name In Type Required Description
projectId path string yes The project id from the projects endpoint.
webhookId path string yes The webhook id from the webhooks list.

Example

curl -X DELETE https://api.himoose.com/v1/projects/PROJECT_ID/webhooks/WEBHOOK_ID \
  -H "Authorization: Bearer hmk_live_..."

Responses

200 Deleted.

Field Type Required Description
deleted boolean no True when the item was removed.

400 A parameter is missing or malformed.

401 The key is missing, malformed, revoked or expired.

403 The account plan does not include the API, or the key lacks the scope.

404 No such resource, or the key cannot read it. The two cases are not told apart.

409 The request is valid but cannot be done right now. The code says why.

429 The per-minute or per-day limit was reached.

Send a ping event now

POST /projects/{projectId}/webhooks/{webhookId}/test

Permission: Manage tracking

Posts a signed ping event so you can check your endpoint and signature code. The response shows the first attempt.

Parameters

Name In Type Required Description
projectId path string yes The project id from the projects endpoint.
webhookId path string yes The webhook id from the webhooks list.

Example

curl -X POST https://api.himoose.com/v1/projects/PROJECT_ID/webhooks/WEBHOOK_ID/test \
  -H "Authorization: Bearer hmk_live_..."

Responses

200 The ping delivery after its first attempt.

Field Type Required Description
id string yes The delivery id, also sent as the X-HiMoose-Delivery header.
event string: run.completed, run.failed, ping yes The event that was delivered.
status string: pending, delivered, failed yes pending while retries remain, delivered on a 2xx answer, failed after the last attempt.
runId string, or null yes The run the event is about, or null for a ping.
requestId string, or null yes The API run request that started the run, or null.
createdAt string (RFC 3339 time), or null yes When the event was created.
deliveredAt string (RFC 3339 time), or null yes When the endpoint answered 2xx, or null.
nextAttemptAt string (RFC 3339 time), or null yes When the next retry is due, or null when none is planned.
attemptCount integer yes How many attempts have been made so far.
attempts array of object yes Every attempt, oldest first.
attempts[].at string (RFC 3339 time) no When the attempt was made.
attempts[].httpStatus integer, or null no The status the endpoint answered, or null when it did not answer.
attempts[].error string, or null no Why the attempt failed, or null.
attempts[].durationMs integer no How long the endpoint took to answer, in milliseconds.

400 A parameter is missing or malformed.

401 The key is missing, malformed, revoked or expired.

403 The account plan does not include the API, or the key lacks the scope.

404 No such resource, or the key cannot read it. The two cases are not told apart.

409 The request is valid but cannot be done right now. The code says why.

429 The per-minute or per-day limit was reached.

Recent deliveries and their attempts

GET /projects/{projectId}/webhooks/{webhookId}/deliveries

Permission: Read visibility data (every key)

Lists the last 50 deliveries for the webhook, newest first, each with every attempt, its HTTP status and error.

Parameters

Name In Type Required Description
projectId path string yes The project id from the projects endpoint.
webhookId path string yes The webhook id from the webhooks list.

Example

curl https://api.himoose.com/v1/projects/PROJECT_ID/webhooks/WEBHOOK_ID/deliveries \
  -H "Authorization: Bearer hmk_live_..."

Responses

200 Newest first, up to 50.

Field Type Required Description
data array of object yes The rows on this page.
data[].id string yes The delivery id, also sent as the X-HiMoose-Delivery header.
data[].event string: run.completed, run.failed, ping yes The event that was delivered.
data[].status string: pending, delivered, failed yes pending while retries remain, delivered on a 2xx answer, failed after the last attempt.
data[].runId string, or null yes The run the event is about, or null for a ping.
data[].requestId string, or null yes The API run request that started the run, or null.
data[].createdAt string (RFC 3339 time), or null yes When the event was created.
data[].deliveredAt string (RFC 3339 time), or null yes When the endpoint answered 2xx, or null.
data[].nextAttemptAt string (RFC 3339 time), or null yes When the next retry is due, or null when none is planned.
data[].attemptCount integer yes How many attempts have been made so far.
data[].attempts array of object yes Every attempt, oldest first.
data[].attempts[].at string (RFC 3339 time) no When the attempt was made.
data[].attempts[].httpStatus integer, or null no The status the endpoint answered, or null when it did not answer.
data[].attempts[].error string, or null no Why the attempt failed, or null.
data[].attempts[].durationMs integer no How long the endpoint took to answer, in milliseconds.
nextCursor string, or null no Pass as cursor to get the next page. Null on the last page.

400 A parameter is missing or malformed.

401 The key is missing, malformed, revoked or expired.

403 The account plan does not include the API, or the key lacks the scope.

404 No such resource, or the key cannot read it. The two cases are not told apart.

409 The request is valid but cannot be done right now. The code says why.

429 The per-minute or per-day limit was reached.

Webhook event payload

The JSON body Hi, Moose posts to a webhook endpoint. See Webhooks for signing and delivery rules.

Field Type Required Description
id string yes Unique event id. Use it to ignore repeats.
event string: run.completed, run.failed, ping yes The event name.
createdAt string (RFC 3339 time) yes When the event was created.
data object yes The event details.
data.projectId string no The project the run belongs to.
data.runId string, or null no The run id to pass as runId on the answers endpoint.
data.requestId string, or null no The API run request that started this run, when there was one.
data.status string no completed, failed or canceled.
data.trigger string no scheduled or manual.
data.startedAt string (RFC 3339 time), or null no When the run started.
data.completedAt string (RFC 3339 time), or null no When the run finished.
data.promptCount integer no How many prompts the run covered.
data.answerCount integer no How many answers the run stored.
data.error string, or null no Why the run failed, or null.
data.links object no Ready-made API addresses for the run's data.
data.links.run string (URL) no The runs endpoint for the project.
data.links.answers string (URL) no The answers endpoint filtered to this run.
data.links.stats string (URL) no The daily stats endpoint for the project.
Errori e limiti Modifiche