Save organization context and case-study sources

This page documents the canonical HTTP contract. Switch to the CLI example when you want the operator workflow.

Use a signed-in user session. Developer API keys are blocked for this route. Records are scoped to the current organization.

This is a multipart form endpoint and requires organization administrator permission. Omitted context fields retain their saved values; unsupported form names return 422. Case-study uploads and URLs are admitted as durable jobs after their source is saved, rather than held in request-lifetime background tasks. The response includes case_study_ids, case_study_processing_status=queued, and case_study_operations only when sources were admitted. Each receipt has case_study_id, job_id, operation_run_id, and status.

A successful save confirms context persistence and source admission, not completed extraction or library materialization. Poll canonical operation runs and case-study reads for completion.

Onboarding context confirmation

With source=onboarding, the saved context is marked confirmed. If fit_rubric is omitted, the response also includes the optional string fit_context_status: ready when the inferred fit context was saved, preserved when the existing rubric should be retained, needs_setup when preparation times out or produces no rubric, or stale when a concurrent context or rubric edit prevents applying the prepared result. These values describe fit-context preparation, independently of case-study ingestion. Re-read organization context after stale; a successful context save alone does not guarantee fit readiness.

For example, an onboarding save without case-study sources can return:

{"success":true,"message":"Organization context saved successfully","fit_context_status":"ready"}

The field is omitted for other source values and when fit_rubric is supplied. The settings example above therefore has no fit_context_status.

Body parameters

sourcerequired
string
Required source label, such as settings or onboarding. Onboarding confirms the saved context and can prepare fit scoring when fit_rubric is omitted.
value_proposition · optional
string
Seller value proposition. Omitted fields retain their saved values.
ideal_titles · optional
string (JSON array)
Target title guidance encoded as JSON.
buyer_persona · optional
string
Buyer persona guidance.
user_persona · optional
string
User persona guidance.
people_personas · optional
string (JSON array)
Structured people personas encoded as JSON.
industries · optional
string
Industry values encoded as JSON or a comma-separated list.
locations · optional
string
Target-company locations encoded as JSON or a comma-separated list.
company_sizes · optional
string
Target company-size values.
include_descriptors · optional
string
Included ICP descriptors encoded as JSON or a comma-separated list.
exclude_descriptors · optional
string
Excluded ICP descriptors encoded as JSON or a comma-separated list.
excluded_companies · optional
string
Company exclusions encoded as JSON or a comma-separated list.
fit_rubric · optional
string (JSON object)
Fit scoring rubric update encoded as JSON. When present, onboarding does not infer a replacement rubric or return fit_context_status.
case_study_files · optional
array<file> (multipart/form-data)
Case-study uploads. Accepted bytes are durably stored before ingestion admission.
case_study_urls · optional
string (JSON array)
URL strings or objects with url/href/link and optional metadata or title/source labels. Sources are saved for durable ingestion.
voice_profile · optional
string
Voice guidance.
workspace_icon_url · optional
string
Workspace icon URL; validated by the branding contract.
company_enrichment · optional
string (JSON object)
Optional seller company information encoded as JSON.
user_title · optional
string
Optional caller title used to update their own profile context.

Name	Type	Description
sourcerequired	string	Required source label, such as settings or onboarding. Onboarding confirms the saved context and can prepare fit scoring when fit_rubric is omitted.
value_proposition	string	Seller value proposition. Omitted fields retain their saved values.
ideal_titles	string (JSON array)	Target title guidance encoded as JSON.
buyer_persona	string	Buyer persona guidance.
user_persona	string	User persona guidance.
people_personas	string (JSON array)	Structured people personas encoded as JSON.
industries	string	Industry values encoded as JSON or a comma-separated list.
locations	string	Target-company locations encoded as JSON or a comma-separated list.
company_sizes	string	Target company-size values.
include_descriptors	string	Included ICP descriptors encoded as JSON or a comma-separated list.
exclude_descriptors	string	Excluded ICP descriptors encoded as JSON or a comma-separated list.
excluded_companies	string	Company exclusions encoded as JSON or a comma-separated list.
fit_rubric	string (JSON object)	Fit scoring rubric update encoded as JSON. When present, onboarding does not infer a replacement rubric or return fit_context_status.
case_study_files	array<file> (multipart/form-data)	Case-study uploads. Accepted bytes are durably stored before ingestion admission.
case_study_urls	string (JSON array)	URL strings or objects with url/href/link and optional metadata or title/source labels. Sources are saved for durable ingestion.
voice_profile	string	Voice guidance.
workspace_icon_url	string	Workspace icon URL; validated by the branding contract.
company_enrichment	string (JSON object)	Optional seller company information encoded as JSON.
user_title	string	Optional caller title used to update their own profile context.

Errors

Status	Meaning
401	A signed-in user session and organization context are required.
403	Developer API keys are blocked, or the caller lacks administrator permission for a write.
404	User or organization not found.
422	Invalid request fields.
500	Context read, save, or case-study admission failed.

Example

bash

curl -X POST "https://app.autotouch.ai/api/org/context" \
  -H "Authorization: Bearer $USER_SESSION_TOKEN" \
  -F "source=settings" \
  -F 'case_study_urls=["https://example.com/case-study"]'

Response example

json

{
  "success": true,
  "message": "Organization context saved successfully (1 URLs queued)",
  "case_study_ids": [
    "case_study_example"
  ],
  "case_study_processing_status": "queued",
  "case_study_operations": [
    {
      "case_study_id": "case_study_example",
      "job_id": "case-study-ingest-example",
      "operation_run_id": "oprun_case_study_example",
      "status": "queued"
    }
  ]
}