{"openapi":"3.1.0","info":{"title":"Syft API","description":"Authenticate with your API key in the X-Syft-API-Key header. Responses are scoped to your organization. For priority accounts, page by passing next_cursor back as cursor while has_more is true. POST /v1/ask and POST /v1/data cost 1 API credit per successful call.","version":"1"},"paths":{"/v1/priority-accounts":{"get":{"summary":"List your workspace's priority accounts","description":"One page of your workspace's priority accounts, highest priority_score first, then most recently detected. Reps see only their assigned accounts. since/until filter last_detected_at; since defaults to 10 days ago. Pass next_cursor unchanged as cursor for the next page, omitting since/until or repeating their original values. total_count covers all pages in the time window.","operationId":"list_priority_accounts_v1_priority_accounts_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","description":"Maximum accounts to return in this page (1-100).","default":20,"title":"Limit"},"description":"Maximum accounts to return in this page (1-100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass the previous response's next_cursor unchanged to get the next page. Omit to start from the beginning. An invalid or expired cursor returns 400; retry without it.","title":"Cursor"},"description":"Pass the previous response's next_cursor unchanged to get the next page. Omit to start from the beginning. An invalid or expired cursor returns 400; retry without it."},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Optional inclusive lower bound (RFC 3339, with timezone) on when an account was last detected; selects accounts with last_detected_at >= since.","title":"Since"},"description":"Optional inclusive lower bound (RFC 3339, with timezone) on when an account was last detected; selects accounts with last_detected_at >= since."},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Optional exclusive upper bound (RFC 3339, with timezone) on when an account was last detected; selects accounts with last_detected_at < until.","title":"Until"},"description":"Optional exclusive upper bound (RFC 3339, with timezone) on when an account was last detected; selects accounts with last_detected_at < until."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriorityAccountsPageWithTotal"}}}},"400":{"description":"Invalid page argument.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"A query parameter could not be parsed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/whoami":{"get":{"summary":"Identify the authenticated caller","description":"Returns the workspace identifier, a non-secret identifier derived from the API key, and the request identifier.","operationId":"whoami_v1_whoami_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhoamiResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"A request parameter could not be parsed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/ask":{"post":{"summary":"Ask a question about accounts","description":"Answers a plain-language question from Syft's evidence, citing numbered facts. Can take minutes. Costs 1 API credit per successful call, including answers that find nothing; failed calls are not charged. Retrying a call charges again. Returns 429 quota_exhausted when your workspace has no credits left.","operationId":"ask_v1_ask_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskResponse"}}}},"400":{"description":"invalid_user_id or invalid_previous_ask_id. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body is invalid. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"quota_exhausted: your workspace has no API credits left. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream service failed. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Temporarily unavailable. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"An upstream service timed out. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/data":{"post":{"summary":"Read one account's observations or documents","description":"Returns one account's extracted facts (observations) or full source documents, newest first, with no pagination. Costs 1 API credit per successful call, including empty results; failed calls are not charged. Retrying a call charges again. Returns 429 quota_exhausted when your workspace has no credits left.","operationId":"read_account_data_v1_data_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body is invalid. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"quota_exhausted: your workspace has no API credits left. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream service failed. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Temporarily unavailable. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"An upstream service timed out. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"APIKeyHeader":[]}]}}},"components":{"schemas":{"AskEvidence":{"properties":{"n":{"type":"integer","title":"N","description":"Citation number used in the answer as [n]."},"id":{"type":"string","title":"Id","description":"Identifier of this observation."},"syft_account_id":{"type":"string","title":"Syft Account Id","description":"Syft's stable identifier for the account."},"account_name":{"type":"string","title":"Account Name","description":"Company name."},"observation":{"type":"string","title":"Observation","description":"The fact, as a self-contained statement."},"quote":{"type":"string","title":"Quote","description":"Verbatim text from the source that grounds the fact."},"people":{"items":{"$ref":"#/components/schemas/Person"},"type":"array","title":"People","description":"Named employees connected to this fact."},"source_type":{"type":"string","title":"Source Type","description":"Kind of source: \"news\", \"jobs\", or \"social_posts\"."},"source_url":{"type":"string","title":"Source Url","description":"Link to the original source."},"published_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Published At","description":"When the source was published, when known. Accurate to the day."},"similarity":{"type":"number","title":"Similarity","description":"Relevance to the question from 0 to 1; 0 when evidence was not searched."},"matched_signal":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Matched Signal","description":"The workspace qualification signal this fact matched, when it matched one."}},"type":"object","required":["n","id","syft_account_id","account_name","observation","quote","people","source_type","source_url","similarity"],"title":"AskEvidence","description":"One numbered fact the answer cites as [n]."},"AskRequest":{"properties":{"question":{"type":"string","maxLength":4000,"minLength":1,"title":"Question","description":"The question in plain language, up to 4000 characters."},"user_id":{"type":"string","minLength":1,"title":"User Id","description":"Syft user id of the person asking; must be an active user in your workspace. Questions about \"my accounts\" use the territory lists this user created."},"syft_account_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"title":"Syft Account Id","description":"Pin the question to one account."},"previous_ask_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"title":"Previous Ask Id","description":"The ask_id of an earlier answer in your workspace, to ask a follow-up."},"days_back":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Days Back","description":"How many days of evidence to look back, at least 1. When omitted, the service picks a window."}},"additionalProperties":false,"type":"object","required":["question","user_id"],"title":"AskRequest","description":"A question about accounts, answered from Syft's evidence with numbered citations."},"AskResponse":{"properties":{"answer":{"type":"string","title":"Answer","description":"The answer, citing evidence as [n]."},"ask_id":{"type":"string","title":"Ask Id","description":"Identifier of this answer; pass it as previous_ask_id to follow up."},"evidence":{"items":{"$ref":"#/components/schemas/AskEvidence"},"type":"array","title":"Evidence","description":"The facts the answer cites."},"quota":{"$ref":"#/components/schemas/Quota"}},"type":"object","required":["answer","ask_id","evidence","quota"],"title":"AskResponse"},"DataRequest":{"properties":{"syft_account_id":{"type":"string","minLength":1,"title":"Syft Account Id","description":"The account to read."},"type":{"type":"string","enum":["observations","documents"],"title":"Type","description":"\"observations\" (default): facts extracted from sources, newest published first. \"documents\": the full source texts, newest collected first.","default":"observations"},"days_back":{"anyOf":[{"type":"integer","maximum":30.0,"minimum":1.0},{"type":"null"}],"title":"Days Back","description":"How many days to look back, 1-30; default 30. Observations filter by publication date, documents by collection date."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Maximum results, default 100; at most 1000 observations or 500 documents. There is no pagination.","default":100}},"additionalProperties":false,"type":"object","required":["syft_account_id"],"title":"DataRequest","description":"Read one account's observations (extracted facts) or documents (full source text)."},"DataResponse":{"properties":{"type":{"type":"string","enum":["observations","documents"],"title":"Type","description":"The type of results returned."},"count":{"type":"integer","title":"Count","description":"Number of results returned."},"results":{"anyOf":[{"items":{"$ref":"#/components/schemas/Observation"},"type":"array"},{"items":{"$ref":"#/components/schemas/Document"},"type":"array"}],"title":"Results","description":"Observations or documents, matching \"type\"."},"quota":{"$ref":"#/components/schemas/Quota"}},"type":"object","required":["type","count","results","quota"],"title":"DataResponse"},"Document":{"properties":{"id":{"type":"string","title":"Id","description":"Identifier of this document (an observation's document_id)."},"syft_account_id":{"type":"string","title":"Syft Account Id","description":"Syft's stable identifier for the account."},"account_name":{"type":"string","title":"Account Name","description":"Company name."},"source_type":{"type":"string","title":"Source Type","description":"Kind of source: \"news\", \"jobs\", or \"social_posts\"."},"source_name":{"type":"string","title":"Source Name","description":"Name of the source."},"source_url":{"type":"string","title":"Source Url","description":"Link to the original source."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Article or job title; absent for social posts."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text","description":"Full source text, when available."},"published_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Published At","description":"When the source was published, when known. Accurate to the day."}},"type":"object","required":["id","syft_account_id","account_name","source_type","source_name","source_url"],"title":"Document","description":"One source document about the account, with its full text."},"ErrorBody":{"properties":{"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"},"request_id":{"type":"string","title":"Request Id"}},"type":"object","required":["code","message","request_id"],"title":"ErrorBody","description":"Machine-readable error details and the request's trace identifier."},"ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/ErrorBody"}},"type":"object","required":["error"],"title":"ErrorResponse","description":"Error response returned by the API."},"Evidence":{"properties":{"reason":{"type":"string","title":"Reason","description":"Why a specific finding about the account makes it a priority for your products."},"quote":{"type":"string","title":"Quote","description":"The exact text from the source that the reason is based on."},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url","description":"URL of the source, when available."},"source_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Title","description":"Title of the source, such as a job posting title or news headline."},"source_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Type","description":"Kind of source: \"news\", \"jobs\", or \"social_posts\". Absent on older evidence."}},"type":"object","required":["reason","quote"],"title":"Evidence","description":"One reason the account is a priority, with the verbatim quote proving it and its source."},"Observation":{"properties":{"id":{"type":"string","title":"Id","description":"Identifier of this observation."},"document_id":{"type":"string","title":"Document Id","description":"The document this fact came from: the id of a type=\"documents\" result."},"syft_account_id":{"type":"string","title":"Syft Account Id","description":"Syft's stable identifier for the account."},"account_name":{"type":"string","title":"Account Name","description":"Company name."},"source_type":{"type":"string","title":"Source Type","description":"Kind of source: \"news\", \"jobs\", or \"social_posts\"."},"source_name":{"type":"string","title":"Source Name","description":"Name of the source."},"source_url":{"type":"string","title":"Source Url","description":"Link to the original source."},"observation":{"type":"string","title":"Observation","description":"The fact, as a self-contained statement."},"quote":{"type":"string","title":"Quote","description":"Verbatim text from the source that grounds the fact."},"people":{"items":{"$ref":"#/components/schemas/Person"},"type":"array","title":"People","description":"Named employees connected to this fact."},"published_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Published At","description":"When the source was published, when known. Accurate to the day."}},"type":"object","required":["id","document_id","syft_account_id","account_name","source_type","source_name","source_url","observation","quote","people"],"title":"Observation","description":"One fact about the account, extracted from a source document."},"Person":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"The person's name, when stated."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Their role or title, when stated."},"reason":{"type":"string","title":"Reason","description":"Why the person is connected to this fact."}},"type":"object","required":["reason"],"title":"Person","description":"A named employee of the account connected to a fact."},"PriorityAccount":{"properties":{"syft_account_id":{"type":"string","title":"Syft Account Id","description":"Syft's stable identifier for the account."},"account_name":{"type":"string","title":"Account Name","description":"Company name."},"account_domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Domain","description":"Primary website domain in lowercase, without a URL scheme or www, when known. Not unique: related companies can share a domain."},"priority_score":{"type":"number","title":"Priority Score","description":"Priority rating from 0 to 100: how real and costly the account's problem is, combined with how completely your products solve it."},"rationale":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rationale","description":"Why this account is a priority."},"value_proposition":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value Proposition","description":"Recommended value proposition, based on the evidence found."},"account_source":{"anyOf":[{"type":"string","enum":["tracked","syft_recommended"]},{"type":"null"}],"title":"Account Source","description":"\"tracked\" when the account is one your workspace tracks, or \"syft_recommended\" when Syft recommends it from outside your tracked accounts."},"evidence":{"anyOf":[{"items":{"$ref":"#/components/schemas/Evidence"},"type":"array"},{"type":"null"}],"title":"Evidence","description":"Reasons the account is a priority, each with the exact source text it is based on and source details when available."},"last_detected_at":{"type":"string","format":"date-time","title":"Last Detected At","description":"When Syft most recently detected this account as a priority."},"first_detected_at":{"type":"string","format":"date-time","title":"First Detected At","description":"When Syft first detected this account as a priority."}},"type":"object","required":["syft_account_id","account_name","priority_score","last_detected_at","first_detected_at"],"title":"PriorityAccount","description":"One account rated a priority for your workspace."},"PriorityAccountsPageWithTotal":{"properties":{"accounts":{"items":{"$ref":"#/components/schemas/PriorityAccount"},"type":"array","title":"Accounts","description":"The priority accounts in this page."},"has_more":{"type":"boolean","title":"Has More","description":"True when another page exists; pass next_cursor back as cursor to get it."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Present only when has_more is true. Pass it unchanged as cursor to get the next page."},"total_count":{"type":"integer","title":"Total Count","description":"Number of priority accounts matching the since/until window across all pages, not just this page."}},"type":"object","required":["accounts","has_more","total_count"],"title":"PriorityAccountsPageWithTotal","description":"One page of priority accounts, with the total for the whole time window."},"Quota":{"properties":{"credits_remaining":{"type":"integer","title":"Credits Remaining","description":"Credits left after this call. Each successful paid call costs 1 credit."}},"type":"object","required":["credits_remaining"],"title":"Quota","description":"Your workspace's API credit balance."},"WhoamiResponse":{"properties":{"tenant_id":{"type":"string","title":"Workspace ID","description":"Identifier of your workspace."},"key_id_prefix":{"type":"string","title":"Key Id Prefix","description":"Non-secret prefix of the API key's SHA-256 hash."},"request_id":{"type":"string","title":"Request Id","description":"Unique identifier of this request, for tracing."}},"type":"object","required":["tenant_id","key_id_prefix","request_id"],"title":"WhoamiResponse","description":"Identity echo for the authenticated caller."}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","description":"Your organization's API key. Required on every /v1 request.","in":"header","name":"X-Syft-API-Key"}}}}