{"openapi":"3.1.0","info":{"title":"Joring External API","description":"External server-to-server API boundary for Joring. Protocol APIs use their own protocol version paths.","license":{"name":""},"version":"1.0.0"},"paths":{"/":{"get":{"tags":[],"operationId":"root","responses":{"200":{"description":"External API metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiMetadata"}}}}}}},"/health":{"get":{"tags":[],"operationId":"health","responses":{"200":{"description":"Shallow API health","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/health/ready":{"get":{"tags":[],"operationId":"readiness","responses":{"200":{"description":"API is ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"503":{"description":"API is not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/openapi.json":{"get":{"tags":[],"operationId":"openapi_json","responses":{"200":{"description":"Generated OpenAPI document"}}}},"/v1/authoring-guide":{"get":{"tags":["agent"],"operationId":"authoring_guide","responses":{"200":{"description":"Rules, limits, tools, existing trails, and the document schema","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthoringGuide"}}}}},"security":[{"bearer":[]}]}},"/v1/content-assets":{"post":{"tags":["assets"],"operationId":"upload_content_asset","requestBody":{"description":"`file` (PNG, JPEG, WebP or GIF, at most 10 MB); optional `trail_id` and `alt`","content":{"multipart/form-data":{}}},"responses":{"201":{"description":"Stored; paste `markdown` into the setup guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentAssetResource"}}}},"413":{"description":"File too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"415":{"description":"Not a supported image","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}},"security":[{"bearer":[]}]}},"/v1/me":{"get":{"tags":["agent"],"operationId":"me","responses":{"200":{"description":"Who the credential acts as","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}}},"security":[{"bearer":[]}]}},"/v1/trails":{"get":{"tags":["trails"],"operationId":"list_trails","parameters":[{"name":"status","in":"path","description":"`draft`, `live` or `archived`.","required":true,"schema":{"type":["string","null"]}},{"name":"q","in":"path","description":"Case-insensitive match on title, role and description (max 200 chars).","required":true,"schema":{"type":["string","null"]}},{"name":"limit","in":"path","description":"Page size, 1 to 100 (default 25).","required":true,"schema":{"type":["integer","null"],"format":"int64"}},{"name":"cursor","in":"path","description":"Opaque cursor from a previous page's `next_cursor`.","required":true,"schema":{"type":["string","null"]}}],"responses":{"200":{"description":"A page of trails, most recently updated first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrailListResponse"}}}},"400":{"description":"Bad cursor, status, or query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}},"security":[{"bearer":[]}]},"post":{"tags":["trails"],"operationId":"create_trail","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTrailBody"}}},"required":true},"responses":{"201":{"description":"The new draft; `Location` and `ETag` are set","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrailDetailResource"}}}},"422":{"description":"The document has validation errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}},"security":[{"bearer":[]}]}},"/v1/trails/{trail_id}":{"get":{"tags":["trails"],"operationId":"get_trail","parameters":[{"name":"trail_id","in":"path","description":"Trail id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The trail with its document and publish issues; `ETag` is the revision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrailDetailResource"}}}},"304":{"description":"Unchanged since the `If-None-Match` revision"},"404":{"description":"No such trail in this catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}},"security":[{"bearer":[]}]},"delete":{"tags":["trails"],"operationId":"delete_trail","parameters":[{"name":"trail_id","in":"path","description":"Trail id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted, along with its versions, grants and sources"}},"security":[{"bearer":[]}]},"patch":{"tags":["trails"],"operationId":"update_trail","parameters":[{"name":"trail_id","in":"path","description":"Trail id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTrailBody"}}},"required":true},"responses":{"200":{"description":"Updated settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrailDetailResource"}}}}},"security":[{"bearer":[]}]}},"/v1/trails/{trail_id}/archive":{"post":{"tags":["trails"],"operationId":"archive","parameters":[{"name":"trail_id","in":"path","description":"Trail id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Archived; hidden from employees and the catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrailDetailResource"}}}}},"security":[{"bearer":[]}]}},"/v1/trails/{trail_id}/document":{"get":{"tags":["trails"],"operationId":"get_document","parameters":[{"name":"trail_id","in":"path","description":"Trail id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The stored draft document; `ETag` is the revision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrailDocument"}}}}},"security":[{"bearer":[]}]},"put":{"tags":["trails"],"operationId":"put_document","parameters":[{"name":"trail_id","in":"path","description":"Trail id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"If-Match","in":"header","description":"The revision you edited from, like \"7\", or * to overwrite","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrailDocument"}}},"required":true},"responses":{"200":{"description":"Saved; the new revision is in `ETag`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrailDetailResource"}}}},"412":{"description":"Someone saved a newer revision; `current_revision` says which","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"description":"The document has validation errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"428":{"description":"`If-Match` is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}},"security":[{"bearer":[]}]}},"/v1/trails/{trail_id}/grants":{"get":{"tags":["grants"],"operationId":"list_grants","parameters":[{"name":"trail_id","in":"path","description":"Trail id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Who can see a restricted trail","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/GrantResource"}}}}}},"security":[{"bearer":[]}]},"post":{"tags":["grants"],"operationId":"add_grant","parameters":[{"name":"trail_id","in":"path","description":"Trail id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddGrantBody"}}},"required":true},"responses":{"200":{"description":"The updated grant list","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/GrantResource"}}}}},"422":{"description":"Not a member of this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}},"security":[{"bearer":[]}]}},"/v1/trails/{trail_id}/grants/{user_id}":{"delete":{"tags":["grants"],"operationId":"revoke_grant","parameters":[{"name":"trail_id","in":"path","description":"Trail id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"user_id","in":"path","description":"The granted user's id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The updated grant list","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/GrantResource"}}}}}},"security":[{"bearer":[]}]}},"/v1/trails/{trail_id}/publish":{"post":{"tags":["trails"],"operationId":"publish","parameters":[{"name":"trail_id","in":"path","description":"Trail id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Live; employees see this revision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrailDetailResource"}}}},"409":{"description":"The trail changed while it was being published, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"description":"Not ready; `issues` lists what to fix","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}},"security":[{"bearer":[]}]}},"/v1/trails/{trail_id}/run-examples":{"post":{"tags":["surfacing"],"operationId":"run_examples","parameters":[{"name":"trail_id","in":"path","description":"Trail id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunExamplesBody"}}},"required":true},"responses":{"200":{"description":"Each example's verdict; the summary is stored on the trail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunExamplesResource"}}}},"422":{"description":"The document has no examples","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}},"security":[{"bearer":[]}]}},"/v1/trails/{trail_id}/surfacing-test":{"post":{"tags":["surfacing"],"operationId":"surfacing_test","parameters":[{"name":"trail_id","in":"path","description":"Trail id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SurfacingTestBody"}}},"required":true},"responses":{"200":{"description":"Whether the trail would surface for that prompt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SurfacingTestResource"}}}}},"security":[{"bearer":[]}]}},"/v1/trails/{trail_id}/unarchive":{"post":{"tags":["trails"],"operationId":"unarchive","parameters":[{"name":"trail_id","in":"path","description":"Trail id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Restored to draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrailDetailResource"}}}}},"security":[{"bearer":[]}]}},"/v1/trails/{trail_id}/unpublish":{"post":{"tags":["trails"],"operationId":"unpublish","parameters":[{"name":"trail_id","in":"path","description":"Trail id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Back to draft; employees no longer see it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrailDetailResource"}}}}},"security":[{"bearer":[]}]}},"/v1/trails/{trail_id}/versions":{"get":{"tags":["versions"],"operationId":"list_versions","parameters":[{"name":"trail_id","in":"path","description":"Trail id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Published versions, newest first","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/VersionResource"}}}}}},"security":[{"bearer":[]}]}},"/v1/trails/{trail_id}/versions/{version}":{"get":{"tags":["versions"],"operationId":"get_version","parameters":[{"name":"trail_id","in":"path","description":"Trail id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"version","in":"path","description":"Version number","required":true,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"The version's document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionDetailResource"}}}}},"security":[{"bearer":[]}]}},"/v1/trails/{trail_id}/versions/{version}/restore":{"post":{"tags":["versions"],"operationId":"restore_version","parameters":[{"name":"trail_id","in":"path","description":"Trail id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"version","in":"path","description":"Version number","required":true,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"The draft now holds that version's document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrailDetailResource"}}}}},"security":[{"bearer":[]}]}}},"components":{"schemas":{"AddGrantBody":{"type":"object","required":["email"],"properties":{"email":{"type":"string","description":"A member of the workspace."}}},"ApiMetadata":{"type":"object","required":["name","version","external_api_host","scim_base_url_template"],"properties":{"external_api_host":{"type":"string"},"name":{"type":"string"},"scim_base_url_template":{"type":"string"},"version":{"type":"string"}}},"AuthoringGuide":{"type":"object","description":"Everything an agent needs before writing a trail.","required":["audience_rule","workflow","field_limits","providers","publish_checklist","existing_trails","document_schema"],"properties":{"audience_rule":{"type":"string","description":"The one rule every field must follow."},"document_schema":{"type":"object","description":"JSON Schema for the `document` body."},"existing_trails":{"type":"array","items":{"$ref":"#/components/schemas/ExistingTrailRef"},"description":"Trails already in the catalog, to avoid duplicates."},"field_limits":{"type":"object","description":"Character and item limits per field."},"providers":{"type":"array","items":{"type":"object"},"description":"The AI tools a trail can target (`tools` values)."},"publish_checklist":{"type":"array","items":{"type":"string"},"description":"What `POST .../publish` checks."},"workflow":{"type":"array","items":{"type":"string"},"description":"The recommended call sequence."}}},"CatalogRef":{"type":"object","required":["kind"],"properties":{"kind":{"type":"string","description":"`team` for a workspace catalog, `joring` for the Joring catalog."},"team_id":{"type":["string","null"],"format":"uuid"},"team_name":{"type":["string","null"]}}},"ContentAssetResource":{"type":"object","required":["url","markdown","key","content_type","size_bytes"],"properties":{"content_type":{"type":"string"},"key":{"type":"string"},"markdown":{"type":"string","description":"Ready-to-paste Markdown image."},"size_bytes":{"type":"integer","minimum":0},"url":{"type":"string"}}},"CreateTrailBody":{"type":"object","properties":{"document":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/TrailDocument","description":"A full document to start from. Validated as a draft."}]},"title":{"type":["string","null"],"description":"Used when `document` is omitted or has no title."}}},"CredentialRef":{"type":"object","required":["kind","id","name"],"properties":{"client_id":{"type":["string","null"],"description":"The OAuth client id; absent for API keys."},"id":{"type":"string","description":"The key id, or a non-secret handle for the OAuth token."},"kind":{"type":"string","description":"`api_key` or `oauth`."},"name":{"type":"string","description":"The key's name, or the OAuth client's name."},"token_prefix":{"type":["string","null"],"description":"The public prefix of an API key; absent for OAuth tokens."}}},"ExampleExpectation":{"type":"string","enum":["match","no_match"]},"ExampleRunResult":{"type":"object","required":["index","expect","would_surface","confidence","reason","pass"],"properties":{"confidence":{"type":"number","format":"double"},"expect":{"$ref":"#/components/schemas/ExampleExpectation"},"index":{"type":"integer","minimum":0},"pass":{"type":"boolean"},"reason":{"type":"string"},"would_surface":{"type":"boolean"}}},"ExistingTrailRef":{"type":"object","required":["id","title","target_role","status"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"target_role":{"type":"string"},"title":{"type":"string"}}},"GrantResource":{"oneOf":[{"type":"object","required":["user_id","email","granted_at","kind"],"properties":{"email":{"type":"string"},"granted_at":{"type":"string","format":"date-time"},"kind":{"type":"string","enum":["user"]},"name":{"type":["string","null"]},"user_id":{"type":"string","format":"uuid"}}},{"type":"object","required":["team_id","team_name","granted_at","kind"],"properties":{"granted_at":{"type":"string","format":"date-time"},"kind":{"type":"string","enum":["team"]},"team_id":{"type":"string","format":"uuid"},"team_name":{"type":"string"}}}]},"HealthResponse":{"type":"object","required":["status","release"],"properties":{"release":{"type":"string","description":"Commit sha the running image was built from (`GIT_SHA` baked into the\ncontainer at build time). Mirrors the frontends' `<meta name=\"release\">`."},"status":{"type":"string"}}},"IssueSeverity":{"type":"string","enum":["error","warning"]},"MeResponse":{"type":"object","required":["user","catalog","scopes","credential"],"properties":{"catalog":{"$ref":"#/components/schemas/CatalogRef"},"credential":{"$ref":"#/components/schemas/CredentialRef"},"scopes":{"type":"array","items":{"type":"string"}},"user":{"$ref":"#/components/schemas/MeUser"}}},"MeUser":{"type":"object","required":["id","name","email"],"properties":{"email":{"type":"string"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"PersonRef":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"ProblemDetails":{"allOf":[{"oneOf":[{"default":null}],"description":"An object containing extensions to this problem details object.\n\nNote that the extensions will be flattened into the resulting problem details\nrepresentation.\n\nSee [https://www.rfc-editor.org/rfc/rfc9457.html#name-extension-members]() for more information."},{"type":"object","properties":{"detail":{"type":["string","null"],"description":"An optional human-readable description of this problem.\n\nSee [https://www.rfc-editor.org/rfc/rfc9457.html#name-detail]() for more information."},"instance":{"type":"string","format":"uri","description":"An optional uri identifying the specific instance of this problem.\n\nSee [https://www.rfc-editor.org/rfc/rfc9457.html#name-instance]() for more information."},"status":{"type":"integer","format":"int32","description":"An optional status code for this problem.\n\nSee [https://www.rfc-editor.org/rfc/rfc9457.html#name-status]() for more information.","minimum":0},"title":{"type":["string","null"],"description":"An optional human-readable title for this problem.\n\nSee [https://www.rfc-editor.org/rfc/rfc9457.html#name-title]() for more information."},"type":{"type":"string","format":"uri","description":"An optional uri describing the problem type.\n\nSee [https://www.rfc-editor.org/rfc/rfc9457.html#name-type]() for more information."}}}],"description":"RFC 9457 / RFC 7807 problem details"},"RunExamplesBody":{"type":"object","properties":{"document":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/TrailDocument","description":"The document whose `trigger.examples` to run. Defaults to the stored\ndraft."}]}}},"RunExamplesResource":{"type":"object","required":["all_pass","results","summary"],"properties":{"all_pass":{"type":"boolean"},"results":{"type":"array","items":{"$ref":"#/components/schemas/ExampleRunResult"}},"summary":{"$ref":"#/components/schemas/SurfacingTestsSummary"}}},"SurfacingTestBody":{"type":"object","required":["draft_text"],"properties":{"document":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/TrailDocument","description":"The document to test. Defaults to the stored draft."}]},"draft_text":{"type":"string","description":"The prompt an employee might type, at most 4,000 characters."}}},"SurfacingTestResource":{"type":"object","required":["would_surface","confidence","reason","candidates"],"properties":{"candidates":{"type":"array","items":{"$ref":"#/components/schemas/TrailRef"},"description":"Every trail the judge compared, this one first."},"confidence":{"type":"number","format":"double"},"reason":{"type":"string"},"winner":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/TrailRef","description":"The live trail that would surface instead, if any."}]},"would_surface":{"type":"boolean"}}},"SurfacingTestsSummary":{"type":"object","required":["last_run_at","all_pass","failing"],"properties":{"all_pass":{"type":"boolean"},"failing":{"type":"array","items":{"type":"integer","minimum":0}},"last_run_at":{"type":"string","format":"date-time"}}},"TrailDetailResource":{"allOf":[{"$ref":"#/components/schemas/TrailResource"},{"type":"object","required":["document","publish_issues"],"properties":{"document":{"$ref":"#/components/schemas/TrailDocument"},"publish_issues":{"type":"array","items":{"$ref":"#/components/schemas/ValidationIssue"},"description":"What still blocks publishing (errors) or would improve surfacing\n(warnings). Empty means `POST .../publish` will succeed."}}}]},"TrailDocument":{"type":"object","description":"The editable one-page body of a trail.","required":["title"],"properties":{"description":{"type":"string","description":"What the employee accomplishes and how AI helps, written to the employee."},"feedback_enabled":{"type":"boolean","description":"Whether learners see the helpful / not helpful widget."},"prompts":{"type":"array","items":{"$ref":"#/components/schemas/TrailPrompt"},"description":"Copy-paste-ready prompts with {{snake_case}} placeholders."},"setup_guide":{"type":"string","description":"Markdown setup guide: tool/mode, connectors or files, model settings, guardrails."},"target_role":{"type":"string","description":"Who does this task, e.g. \"Account Executive, Sales\"."},"title":{"type":"string","description":"Action-oriented title, e.g. \"Respond to a competitor objection in an active deal\"."},"tools":{"type":"array","items":{"type":"string"},"description":"Provider ids (chatgpt, claude, copilot, ...). Empty = any AI tool."},"trigger":{"$ref":"#/components/schemas/TrailTrigger","description":"When this trail applies and how Joring recognizes the moment."}},"additionalProperties":false},"TrailListResponse":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/TrailResource"}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; absent on the last page."}}},"TrailPrompt":{"type":"object","required":["label","body"],"properties":{"body":{"type":"string","description":"The prompt text with {{snake_case}} placeholders for anything the employee supplies."},"id":{"type":"string","description":"Stable id (lowercase letters, digits, `_`, `-`). Assigned by the server when empty."},"label":{"type":"string","description":"Short step title, e.g. \"Analyze the objection\"."}},"additionalProperties":false},"TrailRef":{"type":"object","required":["id","title"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"}}},"TrailResource":{"type":"object","description":"A trail as listed in the catalog. `GET /v1/trails/{id}` adds the\ndocument and publish issues.","required":["id","title","target_role","description","tools","status","visibility","grant_count","prompt_count","sort_order","revision","has_unpublished_changes","created_at","updated_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"created_by":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/PersonRef"}]},"description":{"type":"string"},"grant_count":{"type":"integer","format":"int64","description":"People or teams granted access when `visibility` is `restricted`."},"has_unpublished_changes":{"type":"boolean"},"id":{"type":"string","format":"uuid"},"prompt_count":{"type":"integer","format":"int64"},"published_at":{"type":["string","null"],"format":"date-time"},"published_revision":{"type":["integer","null"],"format":"int32"},"published_version":{"type":["integer","null"],"format":"int32"},"revision":{"type":"integer","format":"int32","description":"Increments on every document save; doubles as the ETag."},"sort_order":{"type":"integer","format":"int32"},"status":{"$ref":"#/components/schemas/TrailStatus"},"surfacing_tests":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/SurfacingTestsSummary"}]},"target_role":{"type":"string"},"title":{"type":"string"},"tools":{"type":"array","items":{"type":"string"}},"updated_at":{"type":"string","format":"date-time"},"visibility":{"$ref":"#/components/schemas/TrailVisibility"}}},"TrailStatus":{"type":"string","enum":["draft","live","archived"]},"TrailTrigger":{"type":"object","properties":{"examples":{"type":"array","items":{"$ref":"#/components/schemas/TriggerExample"},"description":"Sample employee prompts used as surfacing tests and as hints for the matcher."},"keywords":{"type":"array","items":{"type":"string"},"description":"Lowercase phrases the employee would actually type into the AI tool."},"when":{"type":"string","description":"The moment in the workflow when this trail applies, in one or two sentences."}},"additionalProperties":false},"TrailVisibility":{"type":"string","enum":["all_teams","restricted"]},"TriggerExample":{"type":"object","required":["text","expect"],"properties":{"expect":{"$ref":"#/components/schemas/ExampleExpectation","description":"Whether this trail should surface for that prompt."},"text":{"type":"string","description":"A realistic prompt an employee might type."}},"additionalProperties":false},"UpdateTrailBody":{"type":"object","properties":{"sort_order":{"type":["integer","null"],"format":"int32"},"visibility":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/TrailVisibility"}]}}},"ValidationIssue":{"type":"object","required":["severity","field","message"],"properties":{"field":{"type":"string","description":"Dotted path, e.g. `prompts[2].body` or `trigger.keywords`."},"message":{"type":"string"},"severity":{"$ref":"#/components/schemas/IssueSeverity"}}},"VersionDetailResource":{"type":"object","required":["version","created_at","is_live","document"],"properties":{"created_at":{"type":"string","format":"date-time"},"document":{"$ref":"#/components/schemas/TrailDocument"},"is_live":{"type":"boolean"},"note":{"type":["string","null"]},"version":{"type":"integer","format":"int32"}}},"VersionResource":{"type":"object","required":["version","created_at","is_live"],"properties":{"created_at":{"type":"string","format":"date-time"},"created_by":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/PersonRef"}]},"is_live":{"type":"boolean","description":"Whether employees currently see this version."},"note":{"type":["string","null"]},"version":{"type":"integer","format":"int32"}}}},"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"jor_api_...","description":"A personal API key from Settings > API keys (workspaces) or Backstage (Joring catalog). Scopes: trails:read, trails:write, trails:publish."}}},"tags":[{"name":"system","description":"External API system endpoints"},{"name":"scim","description":"SCIM 2.0 Users and Groups provisioning endpoints"},{"name":"agent","description":"Who you are and how to write a trail"},{"name":"trails","description":"Create, edit, publish"},{"name":"versions","description":"Published snapshots"},{"name":"grants","description":"Access to restricted trails"},{"name":"surfacing","description":"Test when a trail surfaces"},{"name":"assets","description":"Images for setup guides"}]}