Create a note

POST

/v1/vault/notes

curl --request POST \
  --url https://api.hyperresearch.ai/v1/vault/notes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "id": "example", "title": "example", "body": "example", "tags": [ "example" ], "aliases": [ "example" ], "status": "example", "type": "example", "tier": "example", "content_type": "example", "source": "example", "summary": "example", "doi": "example", "parent": "example", "raw_r2_key": "example", "fetched_at": "example", "fetch_provider": "example", "utility_score": 1, "authority_score": 1, "centrality_score": 1, "quality_score": 1, "independence": 1, "is_retracted": true, "run_id": "example", "reused_from_run": "example", "rights": { "license": "example", "infer": true, "excerpt": true, "external_report": true, "cache": true, "embed": true, "export": true, "retain": true, "inference_only": true, "exportable": true }, "rights_overlay": { "license": "example", "infer": true, "excerpt": true, "external_report": true, "cache": true, "embed": true, "export": true, "retain": true, "inference_only": true, "exportable": true } }'

• production

Write a note into the workspace vault. title is required; everything else (body, tags, source URL, scores, rights) is optional. Returns the note id; pass id to choose it yourself.

Authorizations

• bearerAuth
  vault:write
• sessionCookie
  vault:write

Request Body^required

Media typeapplication/json

object

id

string

<= 200 characters

title

required

string

>= 1 characters <= 500 characters

body

string

<= 200000 characters

tags

Array<string>

<= 50 items

aliases

Array<string>

<= 50 items

status

string

type

string

tier

string | null

content_type

string | null

<= 200 characters

source

string | null

<= 2000 characters

summary

string | null

<= 20000 characters

doi

string | null

<= 300 characters

parent

string | null

<= 200 characters

raw_r2_key

string | null

<= 500 characters

fetched_at

string | null

<= 60 characters

fetch_provider

string | null

<= 120 characters

utility_score

number | null

authority_score

number | null

centrality_score

number | null

quality_score

number | null

<= 1

independence

number | null

is_retracted

boolean

run_id

string | null

<= 200 characters

reused_from_run

string | null

<= 200 characters

rights

object

license

string | null

<= 200 characters

infer

boolean

excerpt

boolean

external_report

boolean

cache

boolean

embed

boolean

export

boolean

retain

boolean

inference_only

boolean

exportable

boolean

rights_overlay

object

license

string | null

<= 200 characters

infer

boolean

excerpt

boolean

external_report

boolean

cache

boolean

embed

boolean

export

boolean

retain

boolean

inference_only

boolean

exportable

boolean

Example^generated

{
  "id": "example",
  "title": "example",
  "body": "example",
  "tags": [
    "example"
  ],
  "aliases": [
    "example"
  ],
  "status": "example",
  "type": "example",
  "tier": "example",
  "content_type": "example",
  "source": "example",
  "summary": "example",
  "doi": "example",
  "parent": "example",
  "raw_r2_key": "example",
  "fetched_at": "example",
  "fetch_provider": "example",
  "utility_score": 1,
  "authority_score": 1,
  "centrality_score": 1,
  "quality_score": 1,
  "independence": 1,
  "is_retracted": true,
  "run_id": "example",
  "reused_from_run": "example",
  "rights": {
    "license": "example",
    "infer": true,
    "excerpt": true,
    "external_report": true,
    "cache": true,
    "embed": true,
    "export": true,
    "retain": true,
    "inference_only": true,
    "exportable": true
  },
  "rights_overlay": {
    "license": "example",
    "infer": true,
    "excerpt": true,
    "external_report": true,
    "cache": true,
    "embed": true,
    "export": true,
    "retain": true,
    "inference_only": true,
    "exportable": true
  }
}

Responses

201

Created

Media typeapplication/json

object

id

required

string

Example^generated

{
  "id": "example"
}

Headers

RateLimit-Policy

string

Example

"reads";q=60;w=60

The quota policy this request was counted against (draft-ietf-httpapi-ratelimit-headers): "<bucket>";q=<requests>;w=<window seconds>, e.g. "reads";q=60;w=60. Buckets: reads 60/min, status 600/min, creates 10/min, writes 20/min per credential; public 300/min per network on keyless routes.

RateLimit

string

Example

"reads";r=57;t=41

Remaining quota in the current window: "<bucket>";r=<remaining>;t=<seconds until reset>, e.g. "reads";r=57;t=41.

X-RateLimit-Limit

integer

Requests allowed per window in this bucket (legacy form of RateLimit-Policy).

X-RateLimit-Remaining

integer

Requests left in this window (legacy form of RateLimit).

X-RateLimit-Reset

integer

Unix time (seconds) when the window resets.

X-RateLimit-Bucket

string

Which bucket counted the request: reads, status, creates, writes or public.

400

Invalid request

Media typeapplication/json

object

error

required

object

type

required

string

Allowed values: invalid_request authentication permission not_found rate_limited quota_exceeded budget_blocked conflict provider_unavailable internal

code

required

string

Allowed values: missing_api_key malformed_api_key invalid_api_key api_key_expired api_key_revoked account_suspended workspace_unavailable session_expired insufficient_scope signup_closed role_not_permitted membership_required csrf_required csrf_invalid origin_not_allowed https_required key_route_restricted tier_not_allowed runs_paused invalid_body invalid_query invalid_path query_too_short query_not_research query_too_long query_refused invalid_title invalid_brief invalid_must_read invalid_research_brief invalid_time_window invalid_pulse invalid_metadata invalid_tier too_many_required_headings sources_max_above_ceiling reuse_scope_needs_project invalid_webhook_url metadata_too_large invalid_settings invalid_step unsupported_tier tier_not_offered plan_not_offered provider_excluded dry_run_not_enabled invalid_dry_run_fault chaos_faults_not_enabled invalid_chaos_fault gone run_not_found key_not_found workspace_not_found webhook_not_found artifact_not_found note_not_found escalation_not_found source_not_found connection_not_found project_not_found answer_not_found account_not_found feature_not_enabled idempotency_key_reuse idempotency_in_flight run_not_resumable run_not_finish_resumable run_finish_resume_exhausted run_recovering rerun_not_platform platform_rerun_taken run_not_clarifying result_not_ready workspace_not_empty turnstile_invalid turnstile_replayed demo_daily_limit demo_receipt_invalid demo_disabled user_not_found member_not_found member_exists last_owner cannot_self_elevate workspace_limit invitation_not_found invitation_expired invitation_email_mismatch account_mismatch ip_not_allowed chat_keys_retired project_name_taken project_archived run_not_filable confirmation_mismatch ownership_transfer_required account_deleting export_cooldown migration_pending rate_limit_exceeded concurrency_limit spend_cap_exceeded trial_exhausted payment_method_required payment_disputed card_hold_unavailable card_required insufficient_balance wallet_frozen topup_amount_invalid topup_daily_limit answers_capacity platform_capacity daily_run_limit internal_budget orchestrator_unavailable source_unconfigured source_rate_limited source_upstream_unavailable deployment_misconfigured not_implemented pdf_unavailable internal_error

message

required

string

param

string

retry_after

integer

request_id

required

string

Example

{
  "error": {
    "type": "invalid_request",
    "code": "missing_api_key",
    "request_id": "req_01J9ZQ7V6H0000000000000000"
  }
}

401

Authentication failed

Media typeapplication/json

object

error

required

object

type

required

string

Allowed values: invalid_request authentication permission not_found rate_limited quota_exceeded budget_blocked conflict provider_unavailable internal

code

required

string

Allowed values: missing_api_key malformed_api_key invalid_api_key api_key_expired api_key_revoked account_suspended workspace_unavailable session_expired insufficient_scope signup_closed role_not_permitted membership_required csrf_required csrf_invalid origin_not_allowed https_required key_route_restricted tier_not_allowed runs_paused invalid_body invalid_query invalid_path query_too_short query_not_research query_too_long query_refused invalid_title invalid_brief invalid_must_read invalid_research_brief invalid_time_window invalid_pulse invalid_metadata invalid_tier too_many_required_headings sources_max_above_ceiling reuse_scope_needs_project invalid_webhook_url metadata_too_large invalid_settings invalid_step unsupported_tier tier_not_offered plan_not_offered provider_excluded dry_run_not_enabled invalid_dry_run_fault chaos_faults_not_enabled invalid_chaos_fault gone run_not_found key_not_found workspace_not_found webhook_not_found artifact_not_found note_not_found escalation_not_found source_not_found connection_not_found project_not_found answer_not_found account_not_found feature_not_enabled idempotency_key_reuse idempotency_in_flight run_not_resumable run_not_finish_resumable run_finish_resume_exhausted run_recovering rerun_not_platform platform_rerun_taken run_not_clarifying result_not_ready workspace_not_empty turnstile_invalid turnstile_replayed demo_daily_limit demo_receipt_invalid demo_disabled user_not_found member_not_found member_exists last_owner cannot_self_elevate workspace_limit invitation_not_found invitation_expired invitation_email_mismatch account_mismatch ip_not_allowed chat_keys_retired project_name_taken project_archived run_not_filable confirmation_mismatch ownership_transfer_required account_deleting export_cooldown migration_pending rate_limit_exceeded concurrency_limit spend_cap_exceeded trial_exhausted payment_method_required payment_disputed card_hold_unavailable card_required insufficient_balance wallet_frozen topup_amount_invalid topup_daily_limit answers_capacity platform_capacity daily_run_limit internal_budget orchestrator_unavailable source_unconfigured source_rate_limited source_upstream_unavailable deployment_misconfigured not_implemented pdf_unavailable internal_error

message

required

string

param

string

retry_after

integer

request_id

required

string

Example

{
  "error": {
    "type": "invalid_request",
    "code": "missing_api_key",
    "request_id": "req_01J9ZQ7V6H0000000000000000"
  }
}

403

Insufficient scope or plan

Media typeapplication/json

object

error

required

object

type

required

string

Allowed values: invalid_request authentication permission not_found rate_limited quota_exceeded budget_blocked conflict provider_unavailable internal

code

required

string

Allowed values: missing_api_key malformed_api_key invalid_api_key api_key_expired api_key_revoked account_suspended workspace_unavailable session_expired insufficient_scope signup_closed role_not_permitted membership_required csrf_required csrf_invalid origin_not_allowed https_required key_route_restricted tier_not_allowed runs_paused invalid_body invalid_query invalid_path query_too_short query_not_research query_too_long query_refused invalid_title invalid_brief invalid_must_read invalid_research_brief invalid_time_window invalid_pulse invalid_metadata invalid_tier too_many_required_headings sources_max_above_ceiling reuse_scope_needs_project invalid_webhook_url metadata_too_large invalid_settings invalid_step unsupported_tier tier_not_offered plan_not_offered provider_excluded dry_run_not_enabled invalid_dry_run_fault chaos_faults_not_enabled invalid_chaos_fault gone run_not_found key_not_found workspace_not_found webhook_not_found artifact_not_found note_not_found escalation_not_found source_not_found connection_not_found project_not_found answer_not_found account_not_found feature_not_enabled idempotency_key_reuse idempotency_in_flight run_not_resumable run_not_finish_resumable run_finish_resume_exhausted run_recovering rerun_not_platform platform_rerun_taken run_not_clarifying result_not_ready workspace_not_empty turnstile_invalid turnstile_replayed demo_daily_limit demo_receipt_invalid demo_disabled user_not_found member_not_found member_exists last_owner cannot_self_elevate workspace_limit invitation_not_found invitation_expired invitation_email_mismatch account_mismatch ip_not_allowed chat_keys_retired project_name_taken project_archived run_not_filable confirmation_mismatch ownership_transfer_required account_deleting export_cooldown migration_pending rate_limit_exceeded concurrency_limit spend_cap_exceeded trial_exhausted payment_method_required payment_disputed card_hold_unavailable card_required insufficient_balance wallet_frozen topup_amount_invalid topup_daily_limit answers_capacity platform_capacity daily_run_limit internal_budget orchestrator_unavailable source_unconfigured source_rate_limited source_upstream_unavailable deployment_misconfigured not_implemented pdf_unavailable internal_error

message

required

string

param

string

retry_after

integer

request_id

required

string

Example

{
  "error": {
    "type": "invalid_request",
    "code": "missing_api_key",
    "request_id": "req_01J9ZQ7V6H0000000000000000"
  }
}

404

Not found

Media typeapplication/json

object

error

required

object

type

required

string

Allowed values: invalid_request authentication permission not_found rate_limited quota_exceeded budget_blocked conflict provider_unavailable internal

code

required

string

Allowed values: missing_api_key malformed_api_key invalid_api_key api_key_expired api_key_revoked account_suspended workspace_unavailable session_expired insufficient_scope signup_closed role_not_permitted membership_required csrf_required csrf_invalid origin_not_allowed https_required key_route_restricted tier_not_allowed runs_paused invalid_body invalid_query invalid_path query_too_short query_not_research query_too_long query_refused invalid_title invalid_brief invalid_must_read invalid_research_brief invalid_time_window invalid_pulse invalid_metadata invalid_tier too_many_required_headings sources_max_above_ceiling reuse_scope_needs_project invalid_webhook_url metadata_too_large invalid_settings invalid_step unsupported_tier tier_not_offered plan_not_offered provider_excluded dry_run_not_enabled invalid_dry_run_fault chaos_faults_not_enabled invalid_chaos_fault gone run_not_found key_not_found workspace_not_found webhook_not_found artifact_not_found note_not_found escalation_not_found source_not_found connection_not_found project_not_found answer_not_found account_not_found feature_not_enabled idempotency_key_reuse idempotency_in_flight run_not_resumable run_not_finish_resumable run_finish_resume_exhausted run_recovering rerun_not_platform platform_rerun_taken run_not_clarifying result_not_ready workspace_not_empty turnstile_invalid turnstile_replayed demo_daily_limit demo_receipt_invalid demo_disabled user_not_found member_not_found member_exists last_owner cannot_self_elevate workspace_limit invitation_not_found invitation_expired invitation_email_mismatch account_mismatch ip_not_allowed chat_keys_retired project_name_taken project_archived run_not_filable confirmation_mismatch ownership_transfer_required account_deleting export_cooldown migration_pending rate_limit_exceeded concurrency_limit spend_cap_exceeded trial_exhausted payment_method_required payment_disputed card_hold_unavailable card_required insufficient_balance wallet_frozen topup_amount_invalid topup_daily_limit answers_capacity platform_capacity daily_run_limit internal_budget orchestrator_unavailable source_unconfigured source_rate_limited source_upstream_unavailable deployment_misconfigured not_implemented pdf_unavailable internal_error

message

required

string

param

string

retry_after

integer

request_id

required

string

Example

{
  "error": {
    "type": "invalid_request",
    "code": "missing_api_key",
    "request_id": "req_01J9ZQ7V6H0000000000000000"
  }
}

429

Rate limited or over quota

Media typeapplication/json

object

error

required

object

type

required

string

Allowed values: invalid_request authentication permission not_found rate_limited quota_exceeded budget_blocked conflict provider_unavailable internal

code

required

string

Allowed values: missing_api_key malformed_api_key invalid_api_key api_key_expired api_key_revoked account_suspended workspace_unavailable session_expired insufficient_scope signup_closed role_not_permitted membership_required csrf_required csrf_invalid origin_not_allowed https_required key_route_restricted tier_not_allowed runs_paused invalid_body invalid_query invalid_path query_too_short query_not_research query_too_long query_refused invalid_title invalid_brief invalid_must_read invalid_research_brief invalid_time_window invalid_pulse invalid_metadata invalid_tier too_many_required_headings sources_max_above_ceiling reuse_scope_needs_project invalid_webhook_url metadata_too_large invalid_settings invalid_step unsupported_tier tier_not_offered plan_not_offered provider_excluded dry_run_not_enabled invalid_dry_run_fault chaos_faults_not_enabled invalid_chaos_fault gone run_not_found key_not_found workspace_not_found webhook_not_found artifact_not_found note_not_found escalation_not_found source_not_found connection_not_found project_not_found answer_not_found account_not_found feature_not_enabled idempotency_key_reuse idempotency_in_flight run_not_resumable run_not_finish_resumable run_finish_resume_exhausted run_recovering rerun_not_platform platform_rerun_taken run_not_clarifying result_not_ready workspace_not_empty turnstile_invalid turnstile_replayed demo_daily_limit demo_receipt_invalid demo_disabled user_not_found member_not_found member_exists last_owner cannot_self_elevate workspace_limit invitation_not_found invitation_expired invitation_email_mismatch account_mismatch ip_not_allowed chat_keys_retired project_name_taken project_archived run_not_filable confirmation_mismatch ownership_transfer_required account_deleting export_cooldown migration_pending rate_limit_exceeded concurrency_limit spend_cap_exceeded trial_exhausted payment_method_required payment_disputed card_hold_unavailable card_required insufficient_balance wallet_frozen topup_amount_invalid topup_daily_limit answers_capacity platform_capacity daily_run_limit internal_budget orchestrator_unavailable source_unconfigured source_rate_limited source_upstream_unavailable deployment_misconfigured not_implemented pdf_unavailable internal_error

message

required

string

param

string

retry_after

integer

request_id

required

string

Example

{
  "error": {
    "type": "invalid_request",
    "code": "missing_api_key",
    "request_id": "req_01J9ZQ7V6H0000000000000000"
  }
}

Headers

Retry-After

integer

Seconds to wait before retrying. Always present on a 429.

RateLimit-Policy

string

Example

"reads";q=60;w=60

The quota policy this request was counted against (draft-ietf-httpapi-ratelimit-headers): "<bucket>";q=<requests>;w=<window seconds>, e.g. "reads";q=60;w=60. Buckets: reads 60/min, status 600/min, creates 10/min, writes 20/min per credential; public 300/min per network on keyless routes.

RateLimit

string

Example

"reads";r=57;t=41

Remaining quota in the current window: "<bucket>";r=<remaining>;t=<seconds until reset>, e.g. "reads";r=57;t=41.

X-RateLimit-Limit

integer

Requests allowed per window in this bucket (legacy form of RateLimit-Policy).

X-RateLimit-Remaining

integer

Requests left in this window (legacy form of RateLimit).

X-RateLimit-Reset

integer

Unix time (seconds) when the window resets.

X-RateLimit-Bucket

string

Which bucket counted the request: reads, status, creates, writes or public.

500

Internal error

Media typeapplication/json

object

error

required

object

type

required

string

Allowed values: invalid_request authentication permission not_found rate_limited quota_exceeded budget_blocked conflict provider_unavailable internal

code

required

string

Allowed values: missing_api_key malformed_api_key invalid_api_key api_key_expired api_key_revoked account_suspended workspace_unavailable session_expired insufficient_scope signup_closed role_not_permitted membership_required csrf_required csrf_invalid origin_not_allowed https_required key_route_restricted tier_not_allowed runs_paused invalid_body invalid_query invalid_path query_too_short query_not_research query_too_long query_refused invalid_title invalid_brief invalid_must_read invalid_research_brief invalid_time_window invalid_pulse invalid_metadata invalid_tier too_many_required_headings sources_max_above_ceiling reuse_scope_needs_project invalid_webhook_url metadata_too_large invalid_settings invalid_step unsupported_tier tier_not_offered plan_not_offered provider_excluded dry_run_not_enabled invalid_dry_run_fault chaos_faults_not_enabled invalid_chaos_fault gone run_not_found key_not_found workspace_not_found webhook_not_found artifact_not_found note_not_found escalation_not_found source_not_found connection_not_found project_not_found answer_not_found account_not_found feature_not_enabled idempotency_key_reuse idempotency_in_flight run_not_resumable run_not_finish_resumable run_finish_resume_exhausted run_recovering rerun_not_platform platform_rerun_taken run_not_clarifying result_not_ready workspace_not_empty turnstile_invalid turnstile_replayed demo_daily_limit demo_receipt_invalid demo_disabled user_not_found member_not_found member_exists last_owner cannot_self_elevate workspace_limit invitation_not_found invitation_expired invitation_email_mismatch account_mismatch ip_not_allowed chat_keys_retired project_name_taken project_archived run_not_filable confirmation_mismatch ownership_transfer_required account_deleting export_cooldown migration_pending rate_limit_exceeded concurrency_limit spend_cap_exceeded trial_exhausted payment_method_required payment_disputed card_hold_unavailable card_required insufficient_balance wallet_frozen topup_amount_invalid topup_daily_limit answers_capacity platform_capacity daily_run_limit internal_budget orchestrator_unavailable source_unconfigured source_rate_limited source_upstream_unavailable deployment_misconfigured not_implemented pdf_unavailable internal_error

message

required

string

param

string

retry_after

integer

request_id

required

string

Example

{
  "error": {
    "type": "invalid_request",
    "code": "missing_api_key",
    "request_id": "req_01J9ZQ7V6H0000000000000000"
  }
}