openapi: 3.2.0
info:
title: Cyware Intel Exchange (CTIX) v3 Open PIR API
version: 3.6.2
description: 'Public Open API for Cyware Intel Exchange (formerly CTIX), Cyware''s threat intelligence platform for the ingestion, enrichment, analysis, correlation and bi-directional sharing of structured and unstructured threat intelligence using STIX 2.x and TAXII 2.x. The API covers threat data objects, intel creation and import, enrichment, rules, tags, watchlists, threat bulletins, threat investigation, dashboards, reports, PIR management, MITRE ATT&CK navigator data and platform administration.
Intel Exchange is deployed per tenant, so the server host is the customer''s own Intel Exchange deployment; the API is mounted under `/ctixapi`.
This document was assembled by API Evangelist from Cyware''s own published, structured API reference documents at https://ctixapiv3.cyware.com — each endpoint page is served as machine-readable markdown carrying a JSON endpoint model, and every page is indexed from that host''s llms.txt. Paths, methods, parameters, descriptions, enumerations and examples are reproduced from those documents; nothing is invented.'
contact:
name: Cyware
url: https://www.cyware.com/contact-us
termsOfService: https://www.cyware.com/legal/terms-of-use
x-apievangelist-source: https://ctixapiv3.cyware.com/llms.txt
x-apievangelist-method: generated
servers:
- url: https://{ctix_host}/ctixapi
description: Tenant Intel Exchange deployment. Replace {ctix_host} with your own Intel Exchange host. Cyware documents the base URL form https://sample.domain.com/ctixapi in its authentication guide and uses https://demo.cyware.com/ctix/ as the example host in the config of its open-source MCP server.
variables:
ctix_host:
default: demo.cyware.com
security:
- ctixOpenApiSignature: []
tags:
- name: PIR
description: PIR
paths:
/cpapi/rest-auth/login/:
post:
operationId: login
summary: Login
tags:
- PIR
description: "Authenticates a user against the API Gateway and returns a session token. Store the token and pass it as `CYW <token>` in the `Authorization` header for all subsequent API calls.\n\n<Callout attributes='{\"isFitToPage\":true,\"dataType\":\"success\",\"style\":{\"width\":\"100%\",\"minWidth\":\"100%\"}}'>\n <p>The login endpoint is served under <code class=\"slate-code\">/cpapi</code>, not under the <code class=\"slate-code\">/cpapi/cpir</code> prefix used by all other PIR endpoints.</p>\n</Callout>"
externalDocs:
description: Cyware Intel Exchange API reference
url: https://ctixapiv3.cyware.com/pir/auth/login
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
email:
type: string
description: Pass the user's email address.
examples:
- <email>
password:
type: string
description: Pass the user's password.
examples:
- <password>
required:
- email
- password
example:
email: <email>
password: <password>
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
properties:
token:
type: string
description: Returns the session token to use as `CYW <token>` in the `Authorization` header for all authenticated requests.
examples:
- e1a2b3c4d5f6...
email:
type: string
description: Returns the email address of the authenticated user.
examples:
- john.doe@example.com
example:
token: e1a2b3c4d5f6...
email: john.doe@example.com
/api/v1/pirs/{pir_id}/matches/delink/:
post:
operationId: bulkDelinkEntities
summary: Bulk Delink Entities
tags:
- PIR
description: Manually remove one or more intelligence objects from a PIR by setting their link status to `manual_delink`. Delinked entities are permanently suppressed from auto-relinking on future sweep cycles unless manually linked again. Triggers a match snapshot write on success.
externalDocs:
description: Cyware Intel Exchange API reference
url: https://ctixapiv3.cyware.com/pir/matches/bulk-delink-entities
parameters:
- name: pir_id
in: path
required: true
schema:
type: string
description: Pass the KSUID or human-readable ID of the PIR as a path parameter.
description: Pass the KSUID or human-readable ID of the PIR as a path parameter.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
entity_ids:
type: array
description: Pass a list of CES entity IDs to delink.
items:
type: string
description: This is an example value.
examples:
- ces-chunk-abc123
required:
- entity_ids
example:
entity_ids:
- ces-chunk-abc123
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
properties:
updated:
type: number
description: Returns the number of entity records whose link status was set to `manual_delink`.
examples:
- 1
example:
updated: 1
/api/v1/pirs/{pir_id}/matches/link/:
post:
operationId: bulkLinkEntities1
summary: Bulk Link Entities
tags:
- PIR
description: Manually links one or more intelligence objects to a PIR by setting their link status to `manual_link`. The entities must already exist as match records for the PIR. If an entity is not a match record for this PIR, it is silently skipped, and the `updated` count reflects only the entities that were actually changed. Triggers a match snapshot write on success.
externalDocs:
description: Cyware Intel Exchange API reference
url: https://ctixapiv3.cyware.com/pir/matches/bulk-link-entities-1
parameters:
- name: pir_id
in: path
required: true
schema:
type: string
description: Pass the KSUID or human-readable ID of the PIR as a path parameter.
description: Pass the KSUID or human-readable ID of the PIR as a path parameter.
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
entity_ids:
type: array
description: 'Pass a list of CES entity IDs to link. Pass an empty array to receive `updated: 0` without an error.'
items:
type: string
description: This is an example value.
examples:
- ces-chunk-abc123
example:
entity_ids:
- ces-chunk-abc123
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
properties:
updated:
type: number
description: Returns the number of entity records whose link status was changed to `manual_link`.
examples:
- 2
example:
updated: 2
/api/v1/pirs/{pir_id}/matches/:
get:
operationId: listEntityMatchesForPir
summary: List Entity Matches for PIR
tags:
- PIR
description: "Returns the intelligence objects currently matched to a specific PIR, ordered by relevance score in descending by default. At least one of `include__object_type`, `object_type`, or `entity_kind` is required; omitting all three returns `400` `CPIR-002`.\n\n<Callout attributes='{\"isFitToPage\":true,\"dataType\":\"info\",\"style\":{\"width\":\"100%\",\"minWidth\":\"100%\"}}'>\n <p><code class=\"slate-code\">object_type</code> now applies AND semantics across multiple values. Because each matched row holds a single object type, a multi-value AND is structurally unsatisfiable and always returns an empty result. Use <code class=\"slate-code\">include__object_type</code> for OR filtering across multiple types. Single-value <code class=\"slate-code\">object_type</code> is unaffected.</p>\n</Callout>"
externalDocs:
description: Cyware Intel Exchange API reference
url: https://ctixapiv3.cyware.com/pir/matches/list-entity-matches-for-pir
parameters:
- name: include_object_type
in: query
required: false
schema:
type: string
description: Pass a comma-separated list of object types. Returns matches whose type is any of the listed values (OR semantics).
description: Pass a comma-separated list of object types. Returns matches whose type is any of the listed values (OR semantics).
- name: object_type
in: query
required: false
schema:
type: string
description: Pass a single object type. Returns matches of exactly that type. Takes precedence over `include__object_type` when both are present. Do not pass multiple comma-separated values; multi-value AND always returns an empty result set.
description: Pass a single object type. Returns matches of exactly that type. Takes precedence over `include__object_type` when both are present. Do not pass multiple comma-separated values; multi-value AND always returns an empty result set.
- name: entity_kind
in: query
required: false
schema:
type: string
description: Pass an entity kind to expand to all object types within that kind.
enum:
- threat_object
- rss_item
- twitter_post
- threat_bulletin
- threatmailbox
- note
- document
description: Pass an entity kind to expand to all object types within that kind.
- name: page
in: query
required: false
schema:
type: string
description: Pass the page number to retrieve.
description: Pass the page number to retrieve.
- name: page_size
in: query
required: false
schema:
type: string
description: Pass the number of results per page.
description: Pass the number of results per page.
- name: overview
in: query
required: false
schema:
type: string
description: Pass `true` to return the top 7 matches by sort order, ignoring pagination.
description: Pass `true` to return the top 7 matches by sort order, ignoring pagination.
- name: sort
in: query
required: false
schema:
type: string
description: Pass the sort order.
enum:
- -score
- score
- -first_matched_at
- first_matched_at
default: -score
description: Pass the sort order.
- name: q
in: query
required: false
schema:
type: string
description: Pass a keyword for a case-insensitive substring search across entity name, tags, and source tags.
description: Pass a keyword for a case-insensitive substring search across entity name, tags, and source tags.
- name: pir_id
in: path
required: true
schema:
type: string
description: Pass the KSUID or human-readable ID of the PIR as a path parameter.
description: Pass the KSUID or human-readable ID of the PIR as a path parameter.
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
properties:
results:
type: array
description: Returns a list of matched entity objects for the PIR.
items:
type: object
properties:
ces_entity_id:
type: string
description: Returns the CES entity identifier.
examples:
- ces-chunk-abc123
object_id:
type: string
description: Returns the object identifier from the source product.
examples:
- obj-lockbit-3
object_type:
type: string
description: Returns the STIX object type.
examples:
- malware
source_product_type:
type: string
description: Returns the STIX type of the matched object in the source product.
examples:
- malware
score:
type: number
description: Returns the semantic similarity score (0–1) from the vector search.
examples:
- 0.91
link_status:
type: string
description: Returns the current link state.
enum:
- auto_link
- manual_link
- manual_delink
examples:
- auto_link
first_matched_at:
type: string
description: Returns the timestamp when this object was first matched to the PIR.
examples:
- '2026-05-15T10:00:00Z'
last_matched_at:
type: string
description: Returns the timestamp of the most recent match update.
examples:
- '2026-05-19T14:00:00Z'
metadata:
type: object
description: Returns entity metadata. Same shape as the Top Objects by Type endpoint.
properties:
object_type:
type: string
description: Returns the STIX type.
examples:
- malware
tlp:
type: string
description: Returns the TLP marking.
examples:
- amber
source_name:
type: array
description: Returns the deduped list of source feed names that contributed to this object.
items:
type: string
description: This is an example value.
examples:
- feed-a
risk_severity:
type: string
description: Returns the risk severity from the source product. Omitted when not supplied by CES.
examples:
- high
name:
type: string
description: Returns the display name of the object.
examples:
- LockBit 3.0
tags:
type: array
description: Returns the union of all tags across entity variants.
items:
type: string
description: This is an example value.
examples:
- ransomware
description_preview:
type: string
description: Returns a truncated description.
examples:
- LockBit 3.0 ransomware variant observed targeting...
collection_id:
type: string
description: Returns the CES collection identifier.
examples:
- col-123
source_id:
type: string
description: Returns the CES source identifier.
examples:
- src-9
source_tags:
type: array
description: Returns tags from the originating source feed.
items:
type: string
description: This is an example value.
examples:
- apac
cvss_score:
type: number
description: Returns the CVSS score for vulnerability objects. Omitted when CES does not supply any CVSS field. A real score of `0` is preserved.
examples:
- 8.6
object_created_at:
type: string
description: Returns the timestamp when the object was ingested into the source product. Omitted when not supplied by CES.
examples:
- '2026-05-15T10:00:00Z'
object_modified_at:
type: string
description: Returns the most recent modification timestamp from the source product. Omitted when not supplied by CES.
examples:
- '2026-05-18T12:30:00Z'
total:
type: number
description: Returns the total number of matching objects.
examples:
- 1
example:
results:
- ces_entity_id: ces-chunk-abc123
object_id: obj-lockbit-3
object_type: malware
source_product_type: malware
score: 0.91
link_status: auto_link
first_matched_at: '2026-05-15T10:00:00Z'
last_matched_at: '2026-05-19T14:00:00Z'
metadata:
object_type: malware
tlp: amber
source_name:
- feed-a
risk_severity: high
name: LockBit 3.0
tags:
- ransomware
description_preview: LockBit 3.0 ransomware variant observed targeting...
collection_id: col-123
source_id: src-9
source_tags:
- apac
cvss_score: 8.6
object_created_at: '2026-05-15T10:00:00Z'
object_modified_at: '2026-05-18T12:30:00Z'
total: 1
/api/v1/pirs/matches/{object_type}/:
get:
operationId: topObjectsByTypeCrossPir
summary: Top Objects by Type (Cross-PIR)
tags:
- PIR
description: Returns intelligence objects of a given type ranked by the number of active PIRs they are linked to. Use this for a tenant-wide view of which objects are most broadly relevant across all requirements. Pass `overview=true` to retrieve the top 7 objects for use in dashboard widgets, bypassing standard pagination.
externalDocs:
description: Cyware Intel Exchange API reference
url: https://ctixapiv3.cyware.com/pir/matches/top-objects-by-type-cross-pir
parameters:
- name: page
in: query
required: false
schema:
type: string
description: Pass the page number to retrieve.
description: Pass the page number to retrieve.
- name: page_size
in: query
required: false
schema:
type: string
description: Pass the number of results per page.
description: Pass the number of results per page.
- name: Boolean
in: query
required: false
schema:
type: string
description: Pass `true` to return the top 7 objects by `link_count`, ignoring pagination. Intended for dashboard widget use.
description: Pass `true` to return the top 7 objects by `link_count`, ignoring pagination. Intended for dashboard widget use.
- name: q
in: query
required: false
schema:
type: string
description: Pass a keyword for a case-insensitive substring search across object name, tags, and source tags.
description: Pass a keyword for a case-insensitive substring search across object name, tags, and source tags.
- name: object_type
in: path
required: true
schema:
type: string
description: Pass the object type as a path parameter. Unknown values return an empty result set without an error.
enum:
- threat-actor
- intrusion-set
- malware
- attack-pattern
- vulnerability
- campaign
- report
- course-of-action
- identity
- infrastructure
- location
- malware-analysis
- opinion
- tool
- custom-object
- incident
- grouping
- rss_item
- twitter_post
- threat_bulletin
- threatmailbox
- note
- document
description: Pass the object type as a path parameter. Unknown values return an empty result set without an error.
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
properties:
results:
type: array
description: Returns a ranked list of matched intelligence objects.
items:
type: object
properties:
object_id:
type: string
description: Returns the object identifier from the source product.
examples:
- obj-lockbit-3
object_type:
type: string
description: Returns the STIX object type.
examples:
- malware
link_count:
type: number
description: Returns the number of distinct active PIRs this object is linked to.
examples:
- 5
first_matched_at:
type: string
description: Returns the earliest timestamp this object was matched across all linked PIRs.
examples:
- '2026-05-15T10:00:00Z'
metadata:
type: object
description: Returns the display name of the object.
properties:
object_type:
type: string
description: Returns the STIX type.
examples:
- malware
tlp:
type: string
description: Returns the TLP marking.
examples:
- amber
source_name:
type: array
description: Returns the deduped list of source feed names that contributed to this object.
items:
type: string
description: This is an example value.
examples:
- feed-a
risk_severity:
type: string
description: Returns the risk severity from the source product. Omitted when not supplied by CES.
examples:
- high
name:
type: string
description: Returns the display name of the object.
examples:
- LockBit 3.0
tags:
type: array
description: Returns the union of all tags across entity variants.
items:
type: string
description: This is an example value.
examples:
- ransomware
description_preview:
type: string
description: Returns a truncated description.
examples:
- LockBit 3.0 ransomware variant observed targeting...
collection_id:
type: string
description: Returns the CES collection identifier.
examples:
- col-123
source_id:
type: string
description: Returns the CES source identifier.
examples:
- src-9
source_tags:
type: array
description: Returns tags from the originating source feed.
items:
type: string
description: This is an example value.
examples:
- apac
cvss_score:
type: number
description: Returns the CVSS score for vulnerability objects. Omitted when CES does not supply any CVSS field. A real score of `0` is preserved.
examples:
- 8.6
object_created_at:
type: string
description: Returns the timestamp when the object was ingested into the source product. Omitted when not supplied by CES.
examples:
- '2026-05-15T10:00:00Z'
object_modified_at:
type: string
description: Returns the most recent modification timestamp from the source product. Omitted when not supplied by CES.
examples:
- '2026-05-18T12:30:00Z'
total:
type: number
description: Returns the total number of matching objects.
examples:
- 1
example:
results:
- object_id: obj-lockbit-3
object_type: malware
link_count: 5
first_matched_at: '2026-05-15T10:00:00Z'
metadata:
object_type: malware
tlp: amber
source_name:
- feed-a
risk_severity: high
name: LockBit 3.0
tags:
- ransomware
description_preview: LockBit 3.0 ransomware variant observed targeting...
collection_id: col-123
source_id: src-9
source_tags:
- apac
cvss_score: 8.6
object_created_at: '2026-05-15T10:00:00Z'
object_modified_at: '2026-05-18T12:30:00Z'
total: 1
/api/v1/pirs/analyze-intent/:
post:
operationId: analyseIntent
summary: Analyse Intent
tags:
- PIR
description: 'Evaluates a proposed intent string across four quality dimensions without persisting any data. Returns a composite quality score, per-dimension scores, suggested improvements, and a suggested title and category. Use this before creating or updating a PIR to surface gaps in the intent before committing.
Requires LiteLLM. When the LLM is unavailable, all dimension scores and the quality score return as zero and a default set of suggestion chips is returned.'
externalDocs:
description: Cyware Intel Exchange API reference
url: https://ctixapiv3.cyware.com/pir/pir-management/analyse-intent
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
intent:
type: string
description: Pass the intent text to evaluate.
examples:
- Track APT29 against US government
required:
- intent
example:
intent: Track APT29 against US government
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
properties:
quality_dimensions:
type: object
description: Returns per-dimension scores. Each dimension is scored as 0 (fail), 1 (warning), or 2 (pass).
properties:
scope_clarity:
type: number
description: Returns the scope clarity score, indicating how well the intent defines the geographic, sector, or asset boundary.
examples:
- 2
threat_focus:
type: number
description: Returns the threat focus score, indicating how precisely the intent identifies the threat surface.
examples:
- 2
specificity:
type: number
description: Returns the specificity score, indicating how concretely the intent names entities, techniques, or indicators.
examples:
- 1
atomicity:
type: number
descrip
# --- truncated at 32 KB (124 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cyware/refs/heads/main/openapi/cyware-pir-api-openapi.yml