Skip to main content
POST
/
context
/
diagram
/
detect
Python SDK
from cognite.client.data_classes.contextualization import FileReference
detect_job = client.diagrams.detect(
    entities=[
        {"userDefinedField": "21PT1017","ignoredField": "AA11"},
        {"userDefinedField": "21PT1018"}],
    search_field="userDefinedField",
    partial_match=True,
    min_tokens=2,
    file_ids=[101],
    file_external_ids=["Test1"],
    file_references=[
        FileReference(id=20, first_page=1, last_page=10),
        FileReference(external_id="ext_20", first_page=11, last_page=20)
    ])
result = detect_job.result
print(result)

from cognite.client.data_classes.contextualization import ConnectionFlags, DiagramDetectConfig
config = DiagramDetectConfig(
    remove_leading_zeros=True,
    connection_flags=ConnectionFlags(
        no_text_inbetween=True,
        natural_reading_order=True,
    )
)
job = client.diagrams.detect(entities=[{"name": "A1"}], file_id=123, config=config)
{
  "items": [
    {
      "fileId": 1234,
      "pageRange": {
        "begin": 51,
        "end": 100
      }
    }
  ],
  "jobId": 123,
  "status": "Queued",
  "createdTime": 1730204346000,
  "startTime": 1730204346000,
  "statusTime": 1730204346000,
  "errorMessage": null,
  "searchField": "userDefinedField",
  "partialMatch": false,
  "minTokens": 2,
  "configuration": {
    "annotationExtract": true,
    "caseSensitive": true,
    "connectionFlags": [
      "<string>"
    ],
    "customizeFuzziness": {
      "minChars": 123,
      "maxBoxes": 123,
      "fuzzyScore": 1
    },
    "directionDelta": 90,
    "directionWeights": {
      "left": 1,
      "right": 1,
      "up": 1,
      "down": 1
    },
    "minFuzzyScore": 0.85,
    "readEmbeddedText": true,
    "removeLeadingZeros": true,
    "substitutions": {}
  },
  "patternMode": true
}

Authorizations

​
Authorization
string
header
required

Access token issued by the CDF project's configured identity provider. Access token must be an OpenID Connect token, and the project must be configured to accept OpenID Connect tokens. Use a header key of 'Authorization' with a value of 'Bearer $accesstoken'. The token can be obtained through any flow supported by the identity provider.

Body

application/json
​
items
object[]
required

Files to run entity detection on.

Required array length: 1 - 50 elements

Either file id, external id or instance id, and optionally a page range. At most 50 pages can be queried.

​
entities
object[]
required

If not pattern mode: A list of entities to look for. For example, all the assets under a root node. The searchField determines the strings that identify the entities. If pattern mode: The entities represent different types of entities, and detections will follow the same patterns as the samples provided. Letters can be replaced with letters and digits with digits. Brackets indicate strings that must be present, and the pipe symbol indicates alternatives.

Required array length: 1 - 500000 elements
Example:
[
  {
    "userDefinedField": "21PT1017",
    "ignoredField": "AA11"
  },
  {
    "userDefinedField": ["21PT1017-A", "21PT1017-B"]
  },
  {
    "sample": "21PT1017",
    "resourceType": "instrument"
  },
  {
    "sample": ["12-[XP]-123456", "[FILE]-123456[A|B|C]"],
    "resourceType": "file reference"
  }
]
​
searchField
string
default:name

This field determines the string to search for and to identify object entities.

Example:

"userDefinedField"

​
partialMatch
boolean
default:false

Allow partial (fuzzy) matching of entities in the engineering diagrams. Creates a match only when it is possible to do so unambiguously.

​
minTokens
integer
default:2

Each detected item must match the detected entity on at least this number of tokens. A token is a substring of consecutive letters or digits.

​
configuration
object

Configuration for diagram detect that is only available in beta.

​
patternMode
boolean

Only available in beta. If true, entities are not required to contain the search field. Instead they require a field called 'sample'. The sample field can be string, or list of alternative strings. Each string defines a pattern. E.g. 21-PT-1019 enables detecting tags consisting of 2 digits, 2 letters and 4 digits. Special characters are not necessary for detecting, but will be included in the detected string. It is possible to mark parts of the sample as constant strings by enclosing them in square brackets. Within square brackets, a | character can be used to separate alternative constants. Alternative constants must be either all digits or all letters. If false, regular diagram detect is performed, searching for occurrences of the search strings of the entities.

Response

Success

​
items
object[]
required

Either file id, external id or instance id, and optionally a page range. At most 50 pages can be queried.

​
jobId
integer<int64>
required

Contextualization job ID.

Example:

123

​
status
enum<string>
required

The status of the job.

Available options:
Queued,
Running,
Completed,
Failed
​
createdTime
integer<int64>
required

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

Required range: x >= 0
Example:

1730204346000

​
startTime
integer<int64>
required

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

Required range: x >= 0
Example:

1730204346000

​
statusTime
integer<int64>
required

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

Required range: x >= 0
Example:

1730204346000

​
errorMessage
string

If the job failed, some more information about the error cause.

Example:

null

​
searchField
string
default:name

This field determines the string to search for and to identify object entities.

Example:

"userDefinedField"

​
partialMatch
boolean
default:false

Allow partial (fuzzy) matching of entities in the engineering diagrams. Creates a match only when it is possible to do so unambiguously.

​
minTokens
integer
default:2

Each detected item must match the detected entity on at least this number of tokens. A token is a substring of consecutive letters or digits.

​
configuration
object

Configuration for diagram detect that is only available in beta.

​
patternMode
boolean

Only available in beta. If true, entities are not required to contain the search field. Instead they require a field called 'sample'. The sample field can be string, or list of alternative strings. Each string defines a pattern. E.g. 21-PT-1019 enables detecting tags consisting of 2 digits, 2 letters and 4 digits. Special characters are not necessary for detecting, but will be included in the detected string. It is possible to mark parts of the sample as constant strings by enclosing them in square brackets. Within square brackets, a | character can be used to separate alternative constants. Alternative constants must be either all digits or all letters. If false, regular diagram detect is performed, searching for occurrences of the search strings of the entities.

Last modified on April 23, 2026