{"components":{"parameters":{"Common":{"description":"Whether IoCs a warning list marks as not an indicator (public DNS resolvers, private and documentation addresses, ...) stay in the converging list and Explore's IoC ranking (#192). They are marked, never dropped, elsewhere, and every count includes them.","in":"query","name":"common","schema":{"default":"exclude","enum":["exclude","include"]}},"Days":{"description":"The window, in days back from now.","in":"query","name":"days","schema":{"default":30,"maximum":3650,"minimum":1,"type":"integer"}},"Participant":{"description":"Only this organisation (its id).","in":"query","name":"participant","schema":{"type":"string"}},"UserName":{"in":"path","name":"name","required":true,"schema":{"type":"string"}}},"requestBodies":{"Sightings":{"content":{"application/json":{"example":{"sighting":{"last_observed":"2026-10-22T10:00:00Z","observables":{"network":[{"port":443,"role":"c2_server","type":"ipv4","value":"198.51.100.7"}]},"observation_count":3,"sighting_id":"0f8fad5b-d9cb-469f-a165-70867728950e","sigma_detection":{"rule_id":"3b6ab547-8ec2-4991-b9d2-2b06702a48d7"}}},"schema":{"type":["object","array"]}},"application/stix+json":{"schema":{"properties":{"objects":{"items":{"type":"object"},"type":"array"},"type":{"const":"bundle"}},"required":["type","objects"],"type":"object"}},"application/yaml":{"schema":{"type":["object","array"]}}},"description":"One sighting, a list of them, or a STIX 2.1 bundle. JSON and YAML take\nPhase 2's submission format or `frank/1` (what a record holds). A\nbundle takes each `sighting` with its SIGMA `indicator` and the SCOs\nof its `observed-data`; identities and relationships are ignored.\n","required":true}},"responses":{"Conflict":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The change would leave no admin, or strand a role; `error` says what to do first."},"Forbidden":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The caller's status or role is too low."},"NotFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No such object, or one the caller does not manage."},"Unauthorized":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The token is not known."},"Unprocessable":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The request cannot be used; `error` says why."},"UnsupportedType":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The Content-Type is not JSON, YAML or STIX."}},"schemas":{"Error":{"properties":{"error":{"type":"string"}},"type":"object"},"Item":{"properties":{"received":{"format":"date-time","type":"string"},"record":{"$ref":"#/components/schemas/Record"},"reporter":{"description":"The participant id that sent it.","type":"string"},"sighting_id":{"type":"string"}},"type":"object"},"Receipts":{"properties":{"receipts":{"items":{"properties":{"digest":{"description":"SHA-256 of the normalised sighting.","type":"string"},"received":{"description":"First registered","ns since the epoch.":null,"type":"integer"},"sighting_id":{"type":"string"},"status":{"enum":["created","duplicate"]}},"type":"object"},"type":"array"}},"type":"object"},"Record":{"description":"A normalised sighting (`frank/1`). The target's identity is never included.","properties":{"confidence":{"maximum":100,"minimum":0,"type":"integer"},"count":{"minimum":1,"type":"integer"},"description":{"type":"string"},"evidence":{"items":{"properties":{"context":{"description":"The sender's other fields for it: port, protocol, file name, ...","type":"object"},"role":{"description":"The sender's role for it, kept as given.","type":"string"},"type":{"enum":["ipv4","ipv6","domain","url","email","certificate","file_hash","registry_key","mutex"]},"value":{"type":"string"}},"required":["type","value"],"type":"object"},"type":"array"},"first_seen":{"format":"date-time","type":"string"},"format":{"const":"frank/1"},"last_seen":{"format":"date-time","type":"string"},"reporter_sector":{"type":"string"},"severity":{"enum":["info","low","medium","high","critical"]},"sighting_id":{"type":"string"},"sighting_of":{"properties":{"campaign":{"type":"string"},"rule":{"properties":{"id":{"type":"string"},"level":{"enum":["informational","low","medium","high","critical"]},"title":{"type":"string"}},"type":"object"},"techniques":{"items":{"examples":["T1059.001"],"type":"string"},"type":"array"}},"type":"object"},"target":{"properties":{"region":{"type":"string"},"sector":{"type":"string"},"size":{"type":"string"}},"type":"object"},"timestamp":{"format":"date-time","type":"string"},"tlp":{"enum":["clear","green","amber","amber+strict"]}},"required":["format","timestamp","count","confidence","tlp","sighting_of"],"type":"object"},"Role":{"description":"A user's role; `null` or `none` is none.","enum":["admin","superadmin","none",null]},"Status":{"enum":["public","observer","contributor","partner","core"]},"Token":{"properties":{"organisation":{"type":"string"},"participant":{"type":"string"},"prefix":{"description":"The first 12 hex digits of the token's SHA-256.","type":"string"},"revoked":{"type":"boolean"},"user":{"type":"string"}},"type":"object"},"User":{"properties":{"disabled":{"description":"Its tokens do not work while it is disabled.","type":"boolean"},"kind":{"enum":["human","machine"]},"name":{"type":"string"},"organisation":{"type":"string"},"participant":{"description":"The organisation's id.","type":"string"},"role":{"enum":["admin","superadmin",null]}},"type":"object"}},"securitySchemes":{"bearer":{"scheme":"bearer","type":"http"}}},"info":{"description":"FRANK passes on what participants send and does not judge it.\n\nAuthenticate with `Authorization: Bearer <token>`. A token belongs to a\nuser of a participant, and the participant's status (observer,\ncontributor, partner, core) decides what it may see. Each status also\nsees the TLP levels allowed to it; TLP:RED is never accepted.\n","license":{"identifier":"Apache-2.0","name":"Apache-2.0"},"summary":"Sightings of detection rules and indicators, shared between participants.","title":"FRANK","version":"0.18"},"openapi":"3.1.0","paths":{"/health":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"status":{"const":"ok"},"version":{"type":"string"}},"type":"object"}}},"description":"The server is up. `geoip` says whether the DB-IP geo databases are loaded (`ok` with their build day) or `missing`, and `lists` the entries per imported warning and reference list; FRANK is healthy either way (#191, #192)."}},"security":[],"summary":"Liveness and version","tags":["platform"],"x-min-status":"public"}},"/v1/admin/audit":{"get":{"description":"An admin sees the lines about its own organisation (its id, users and tokens, or done by its users); a superadmin all. At most 1000 lines.","parameters":[{"description":"The window in days, up to 31.","in":"query","name":"days","schema":{"default":7,"maximum":31,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"days":{"type":"integer"},"lines":{"items":{"type":"object"},"type":"array"}},"type":"object"}}},"description":"The lines."},"403":{"$ref":"#/components/responses/Forbidden"}},"summary":"The audit log, newest first","tags":["admin"],"x-min-status":"contributor","x-role":"admin"}},"/v1/admin/organisations":{"get":{"description":"An admin's own; every one for a superadmin. Each with its id, name, type, status, sector, region and user names.","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"organisations":{"items":{"type":"object"},"type":"array"}},"type":"object"}}},"description":"The organisations."},"403":{"$ref":"#/components/responses/Forbidden"}},"summary":"The organisations the caller manages","tags":["admin"],"x-min-status":"contributor","x-role":"admin"},"post":{"requestBody":{"content":{"application/json":{"example":{"name":"acme-mdr","sector":"energy","status":"contributor"},"schema":{"properties":{"name":{"description":"1-64 of [A-Za-z0-9._@-]","type":"string"},"region":{"type":"string"},"sector":{"type":"string"},"status":{"$ref":"#/components/schemas/Status"},"type":{"default":"cyber_partner","enum":["cyber_partner","customer"]}},"required":["name","status"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Its id (`identity--{uuid}`), name and status."},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Unprocessable"}},"summary":"Register an organisation","tags":["admin"],"x-min-status":"core","x-role":"superadmin"}},"/v1/admin/organisations/{id}":{"patch":{"description":"Its users have the new status from their next request. Refused while one of its users holds a role the status does not allow.","parameters":[{"description":"The organisation's id.","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"status":"partner"},"schema":{"properties":{"status":{"$ref":"#/components/schemas/Status"}},"required":["status"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"The id and the new status."},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}},"summary":"Change an organisation's status","tags":["admin"],"x-min-status":"core","x-role":"superadmin"}},"/v1/admin/tokens":{"get":{"description":"Each as the first 12 hex digits of its hash, never the token.","parameters":[{"$ref":"#/components/parameters/Participant"}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"tokens":{"items":{"$ref":"#/components/schemas/Token"},"type":"array"}},"type":"object"}}},"description":"The tokens."},"403":{"$ref":"#/components/responses/Forbidden"}},"summary":"The tokens of the users the caller manages","tags":["admin"],"x-min-status":"contributor","x-role":"admin"},"post":{"description":"The token is in this response only (`Cache-Control: no-store`); FRANK keeps its hash.","requestBody":{"content":{"application/json":{"example":{"user":"alice"},"schema":{"properties":{"user":{"type":"string"}},"required":["user"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"prefix":{"type":"string"},"token":{"type":"string"},"user":{"type":"string"}},"type":"object"}}},"description":"The token, its prefix and the user."},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Issue a token for a user","tags":["admin"],"x-min-status":"contributor","x-role":"admin"}},"/v1/admin/tokens/{prefix}":{"delete":{"description":"By at least 8 hex digits of its hash. The caller's own last token is kept.","parameters":[{"in":"path","name":"prefix","required":true,"schema":{"pattern":"^[0-9a-f]{8,64}$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"The revoked prefix and its user."},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}},"summary":"Revoke a token","tags":["admin"],"x-min-status":"contributor","x-role":"admin"}},"/v1/admin/users":{"get":{"parameters":[{"$ref":"#/components/parameters/Participant"}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"users":{"items":{"$ref":"#/components/schemas/User"},"type":"array"}},"type":"object"}}},"description":"The users."},"403":{"$ref":"#/components/responses/Forbidden"}},"summary":"The users the caller manages","tags":["admin"],"x-min-status":"contributor","x-role":"admin"},"post":{"description":"To the caller's own organisation unless `participant` names another a superadmin manages. Only people hold a role; only a superadmin makes a superadmin.","requestBody":{"content":{"application/json":{"example":{"name":"alice","role":"admin"},"schema":{"properties":{"kind":{"default":"human","enum":["human","machine"]},"name":{"description":"1-64 of [A-Za-z0-9._@-], unique on the platform","type":"string"},"participant":{"description":"The organisation's id; the caller's own when missing.","type":"string"},"role":{"$ref":"#/components/schemas/Role"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}},"description":"The user."},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"}},"summary":"Add a user","tags":["admin"],"x-min-status":"contributor","x-role":"admin"}},"/v1/admin/users/{name}":{"delete":{"description":"With its role and tokens; a user is disabled first. Its sightings stay, stored under the organisation. The name can be used again.","parameters":[{"$ref":"#/components/parameters/UserName"}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"The name removed and the prefixes of its tokens."},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}},"summary":"Remove a disabled user","tags":["admin"],"x-min-status":"contributor","x-role":"admin"},"patch":{"description":"Only a superadmin grants or takes superadmin. An organisation's last working admin and the platform's last working superadmin keep their role.","parameters":[{"$ref":"#/components/parameters/UserName"}],"requestBody":{"content":{"application/json":{"example":{"role":"admin"},"schema":{"properties":{"role":{"$ref":"#/components/schemas/Role"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"The user's name and new role."},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}},"summary":"Give a user a role, or take it","tags":["admin"],"x-min-status":"contributor","x-role":"admin"}},"/v1/admin/users/{name}/disable":{"post":{"description":"Its tokens stop working until it is enabled; none are revoked. Not the caller itself, nor an organisation's last working admin or the last working superadmin.","parameters":[{"$ref":"#/components/parameters/UserName"}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"The user's name, disabled."},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}},"summary":"Disable a user","tags":["admin"],"x-min-status":"contributor","x-role":"admin"}},"/v1/admin/users/{name}/enable":{"post":{"description":"Its tokens work again.","parameters":[{"$ref":"#/components/parameters/UserName"}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"The user's name, enabled."},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Enable a disabled user","tags":["admin"],"x-min-status":"contributor","x-role":"admin"}},"/v1/explore":{"get":{"description":"`group` and every filter name a dimension: rule, ioc, campaign,\ntechnique, sector, ioc_type, severity. Sectors, IoC types and\nseverities need observer; the others contributor. Any filter goes\nwith any group, technique by ioc or ioc_type included.\n","parameters":[{"in":"query","name":"group","required":true,"schema":{"enum":["rule","ioc","campaign","technique","sector","ioc_type","severity"]}},{"$ref":"#/components/parameters/Days"},{"in":"query","name":"rule","schema":{"type":"string"}},{"description":"`type:value`","in":"query","name":"ioc","schema":{"type":"string"}},{"in":"query","name":"campaign","schema":{"type":"string"}},{"in":"query","name":"technique","schema":{"type":"string"}},{"in":"query","name":"sector","schema":{"type":"string"}},{"in":"query","name":"ioc_type","schema":{"type":"string"}},{"in":"query","name":"severity","schema":{"type":"string"}},{"$ref":"#/components/parameters/Common"},{"description":"With group=ioc: `any` keeps the IoCs a reference list has (abuse.ch, ...), `none` those no list has, a list name those that list has (#193).","in":"query","name":"listed","schema":{"examples":["none"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Up to 100 groups, most sightings first. Grouped by IoC, each row also has `common` and `listed`, as `/v1/iocs` gives them."},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Unprocessable"}},"summary":"Group sightings by one dimension, filtered by others","tags":["statistics"],"x-min-status":"observer"}},"/v1/files":{"get":{"description":"One row per sighting × IoC: a sighting with three IoCs is three rows,\n`seq` 0, 1 and 2, each with one `ioc_type` and `ioc_value` and the\nsighting's other fields repeated. A sighting without IoCs is one row.\nThe full record (`detail`, `frank/1` JSON) is on the `seq = 0` row only.\nTo count sightings, or to sum `observations`, keep one row per\nsighting: `WHERE seq = 0 OR seq IS NULL` (NULL in rows stored before\n0.15). Without it a sighting counts once per IoC. `count(*)` over all\nrows counts sighting × IoC pairs.\n\n`sighting_id` (16 bytes, the UUID) and `digest` (32 bytes, SHA-256)\nare binary, a `BLOB` in DuckDB (since 0.28, #200); `digest` is on the\n`seq = 0` row only. The text forms of the API and the receipts:\n\n    lower(hex(digest))\n    'sighting--' || lower(regexp_replace(hex(sighting_id),\n      '(.{8})(.{4})(.{4})(.{4})(.{12})', '\\1-\\2-\\3-\\4-\\5'))\n\nOne sighting by id: `WHERE sighting_id = unhex('0f8fad5bd9cb469fa16570867728950e')`.\n\n`ip_geo`, when present, names one more file: the country and ASN of\nevery IP address FRANK has seen (`ip`, `country`, `asn`, `as_org`,\n`looked_up`), to join on `sightings.ioc_value = ip_geo.ip`. It\ncarries the attribution DB-IP's licence (CC BY 4.0) asks for (#191).\n","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Each file's path, rows and bytes, the open hour last."},"403":{"$ref":"#/components/responses/Forbidden"}},"summary":"The sighting Parquet files","tags":["files"],"x-min-status":"partner"}},"/v1/files/{path}":{"get":{"parameters":[{"description":"A path from /v1/files.","in":"path","name":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/vnd.apache.parquet":{}},"description":"The file."},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No such file."}},"summary":"One sighting Parquet file","tags":["files"],"x-min-status":"partner"}},"/v1/iocs":{"get":{"parameters":[{"in":"query","name":"type","required":true,"schema":{"examples":["ipv4"],"type":"string"}},{"in":"query","name":"value","required":true,"schema":{"type":"string"}},{"description":"Limit `panels` to one day, YYYY-MM-DD.","in":"query","name":"day","required":false,"schema":{"format":"date","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Whether it is known, when, by how many reporters, under which rules. `panels` groups its sightings by rule, target sector, severity, technique and campaign, as Explore does: same reporter threshold and TLP rules; over the retained days, or one `day`. For an IP address, `geo` is its country (ISO 3166, `ZZ` when unknown), ASN (0 when unknown) and AS organisation from DB-IP Lite, or null when not looked up (#191). `listed` is what warning lists (common infrastructure, private and documentation addresses) and reference lists (outside sources such as abuse.ch) say about it, each with its list, source and, for references, tags and when it was first listed (#192, #193)."},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Unprocessable"}},"summary":"Look up one IoC","tags":["lookup"],"x-min-status":"contributor"}},"/v1/iocs/range":{"get":{"parameters":[{"in":"query","name":"cidr","required":true,"schema":{"examples":["185.220.0.0/16"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Up to 1000 addresses with their counts."},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Unprocessable"}},"summary":"Known addresses in a CIDR block","tags":["lookup"],"x-min-status":"contributor"}},"/v1/live":{"get":{"description":"By arrival (`received`), not by when a sighting was seen. Counters\nand arrivals per bar (5 minutes for 1h, 30 for 6h, 60 for 24h); the\nwindow's IoCs newest first (`feed`), and those two or more\nparticipants report (`converging`), 50 each. `seen_since` is the\nearliest sighting of the IoC that arrived before the window; null\nmeans it is new. Below partner, an IoC with fewer than `min_cell`\nreporters is left out of both lists; the counters include it.\n\n`places` says where the window's IP addresses are (#195): the top\n10 `countries` (ISO 3166 `country`) and `networks` (`asn`,\n`as_org`), each with its distinct `iocs` and `reporters`, most\nreporters first. `other` is the rest taken together, `unknown` the\naddresses without a country (reserved, or not in DB-IP).\nBelow partner a place with fewer than `min_cell` reporters is not\nshown, and neither is `other` or `unknown` then. Addresses on a\nwarning list are left out unless `common=include`; addresses not\nlooked up yet are left out. `geoip` is `ok` or `missing`.\n","parameters":[{"in":"query","name":"window","schema":{"default":"1h","enum":["1h","6h","24h"]}},{"$ref":"#/components/parameters/Common"}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"The counters, `buckets`, `feed`, `converging`, `geoip` and `places`."},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Unprocessable"}},"summary":"The IoCs of the sightings that arrived recently","tags":["statistics"],"x-min-status":"contributor"}},"/v1/openapi.json":{"get":{"responses":{"200":{"content":{"application/json":{}},"description":"The OpenAPI document."}},"security":[],"summary":"This document, as JSON","tags":["platform"],"x-min-status":"public"}},"/v1/participants":{"get":{"description":"Partners see ids and status; core also names, type, sector and users.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"The participants."},"403":{"$ref":"#/components/responses/Forbidden"}},"summary":"The participants","tags":["platform"],"x-min-status":"partner"}},"/v1/preview":{"post":{"description":"What leaves the sender, shown before it leaves. Nothing is stored.","requestBody":{"$ref":"#/components/requestBodies/Sightings"},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"rows":{"items":{"type":"object"},"type":"array"}},"type":"object"}}},"description":"The rows of the shared `sightings` table."},"415":{"$ref":"#/components/responses/UnsupportedType"},"422":{"$ref":"#/components/responses/Unprocessable"}},"summary":"The rows a submission would share, without storing it","tags":["submit"],"x-min-status":"public"}},"/v1/rules/{id}":{"get":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/Days"}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Counts, trend and breakdowns; `known` false below the reporting threshold."},"403":{"$ref":"#/components/responses/Forbidden"}},"summary":"One rule's prevalence","tags":["lookup"],"x-min-status":"contributor"}},"/v1/sightings":{"get":{"description":"The records of the visible sightings stored since 0.15, a page at a\ntime, filtered by the same dimensions as /v1/explore. Partners and\ncore list all; a contributor lists its own with `mine=true`. Follow\n`next_cursor` until it is null.\n","parameters":[{"description":"From this time (RFC 3339); the last 30 days by default.","in":"query","name":"since","schema":{"format":"date-time","type":"string"}},{"description":"Before this time (RFC 3339).","in":"query","name":"until","schema":{"format":"date-time","type":"string"}},{"description":"Only sightings of this rule id.","in":"query","name":"rule","schema":{"type":"string"}},{"description":"Only sightings carrying this IoC, as `type:value`.","in":"query","name":"ioc","schema":{"examples":["ipv4:198.51.100.7"],"type":"string"}},{"description":"Only sightings with an IoC of this type.","in":"query","name":"ioc_type","schema":{"type":"string"}},{"in":"query","name":"campaign","schema":{"type":"string"}},{"description":"An ATT&CK technique id; not a prefix of others.","in":"query","name":"technique","schema":{"type":"string"}},{"description":"The target's sector.","in":"query","name":"sector","schema":{"type":"string"}},{"in":"query","name":"severity","schema":{"type":"string"}},{"description":"Oldest first (`asc`) or newest first (`desc`).","in":"query","name":"order","schema":{"default":"asc","enum":["asc","desc"]}},{"description":"Only the caller's participant's sightings. Required below partner.","in":"query","name":"mine","schema":{"default":false,"type":"boolean"}},{"description":"The `next_cursor` of the previous page.","in":"query","name":"cursor","schema":{"type":"string"}},{"in":"query","name":"limit","schema":{"default":100,"maximum":500,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"next_cursor":{"type":["string","null"]},"sightings":{"items":{"$ref":"#/components/schemas/Item"},"type":"array"}},"type":"object"}}},"description":"One page."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Unprocessable"}},"summary":"List sighting records","tags":["records"],"x-min-status":"contributor"},"post":{"description":"One sighting, a list of up to 100, or a STIX 2.1 bundle. Each needs a\n`sighting_id` the sender chooses (a UUID): with the participant it is\nthe registration. Sent again with the same content, a sighting gets\nits original receipt (`duplicate`); other content under a registered\nid is a conflict and nothing of the batch is stored.\n","requestBody":{"$ref":"#/components/requestBodies/Sightings"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Receipts"}}},"description":"Every sighting was registered before."},"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Receipts"}}},"description":"At least one sighting was new."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"A sighting id is registered with other content."},"415":{"$ref":"#/components/responses/UnsupportedType"},"422":{"$ref":"#/components/responses/Unprocessable"}},"summary":"Send sightings","tags":["submit"],"x-min-status":"contributor"}},"/v1/sightings/{id}":{"get":{"description":"Below partner, only the caller's participant's own; anything else is 404.","parameters":[{"description":"The sighting id, `sighting--{uuid}` or the bare UUID.","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}},"description":"The record."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No such sighting visible to the caller."},"422":{"$ref":"#/components/responses/Unprocessable"}},"summary":"One sighting record","tags":["records"],"x-min-status":"contributor"}},"/v1/statistics":{"get":{"description":"The public tier sees totals; observers also breakdowns by IoC type,\nseverity and target sector; contributors also the top rules,\ntechniques and campaigns. Below partner a cell with fewer than three\nreporters is left out.\n","parameters":[{"$ref":"#/components/parameters/Days"}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Statistics for the caller's status."}},"summary":"Totals and breakdowns","tags":["statistics"],"x-min-status":"public"}},"/v1/summary":{"get":{"parameters":[{"$ref":"#/components/parameters/Days"}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"days":{"type":"integer"},"iocs":{"description":"Sighting × IoC pairs.","type":"integer"},"last_received":{"format":"date-time","type":["string","null"]},"network":{"properties":{"sightings":{"type":"integer"}},"type":"object"},"observations":{"type":"integer"},"participant":{"type":"string"},"sightings":{"type":"integer"}},"type":"object"}}},"description":"The participant's sightings in the window, and everyone's it can see."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"summary":"What the caller's participant sent","tags":["records"],"x-min-status":"contributor"}},"/v1/whoami":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"label":{"type":"string"},"participant":{"properties":{"id":{"examples":["identity--8c1d2a7e-5b3f-4e6a-9d0c-1f2e3a4b5c6d"],"type":"string"},"name":{"type":"string"},"status":{"$ref":"#/components/schemas/Status"}},"type":"object"},"tier":{"$ref":"#/components/schemas/Status"},"user":{"type":"string"}},"type":"object"}}},"description":"Without a token, only the public tier."},"401":{"$ref":"#/components/responses/Unauthorized"}},"summary":"The caller's status, user and participant","tags":["platform"],"x-min-status":"public"}}},"security":[{"bearer":[]}],"servers":[{"url":"/"}],"tags":[{"description":"Sending sightings.","name":"submit"},{"description":"Sighting records for machine clients.","name":"records"},{"description":"Aggregates, with small cells suppressed below partner.","name":"statistics"},{"description":"IoC and rule lookups.","name":"lookup"},{"description":"The sighting Parquet files, for local analysis.","name":"files"},{"description":"Health, identity, participants and this document.","name":"platform"},{"description":"Organisations, users and tokens, for users with a role. An admin manages its own organisation, a superadmin every one; to an admin, another organisation's objects are 404.","name":"admin"}]}