How annotations work
An annotation references a file (or file version) and a location within it. The location can be a bounding box, a page range, or another spatial descriptor. Annotations can reference assets, events, or other CDF resources as the annotated entity.Creation and review
Annotations can be created directly via the API or suggested for review. AI services like engineering diagrams and vision often produce annotation suggestions that you can accept, reject, or modify before storing.Annotations are stored separately from the file. They persist across file versions when you specify version handling.
Create annotations
Each annotation references an annotated resource by internal ID. Setstatus to suggested, rejected, or approved. You need read access to every annotated resource, or the request fails. annotationType must be a known type, and data must match that type’s schema. Send the creating application and its version. Send the creating user, or null when a service creates the annotation.
Suggest creates the same annotations with status set to suggested. It requires annotationsAcl:SUGGEST. Create requires annotationsAcl:WRITE.
Reverse lookup
Reverse lookup takes an annotation filter and a resource type,file or 3D, and returns the IDs of annotated resources you can access. Use it to find files whose annotations point at one asset. This operation is available on the beta and alpha APIs.
Key capabilities
- Create annotations linking resources to file regions
- Store suggested annotations for review workflows
- Query by file, resource, or type
- Support bounding boxes and page ranges
Reverse lookup
POST /annotations/reverselookup returns the IDs of files or 3D resources whose annotations match a filter. A typical use is finding files that link to a specific asset. The response includes only resources you can access.