> ## Documentation Index > Fetch the complete documentation index at: https://aspect.inc/docs/llms.txt > Use this file to discover all available pages before exploring further. # Search a project > Perform a search operation and return full asset bodies. ## OpenAPI ````yaml /api-reference/openapi.json post /search/run openapi: 3.1.0 info: title: Aspect API description: Manage and search media in Aspect. version: 1.0.0 servers: - url: https://api.aspect.inc security: - ApiKeyAuth: [] tags: - name: Users - name: API Keys - name: Workspaces - name: Projects - name: Directories - name: Assets - name: Attachments - name: Filesystem Items - name: Jobs - name: Collections - name: Comments - name: Search - name: Transcription - name: Metadata - name: Shares - name: Share Templates - name: Watermarks paths: /search/run: post: tags: - Search summary: Search a project description: Perform a search operation and return full asset bodies. operationId: search requestBody: content: application/json: schema: $ref: '#/components/schemas/SearchRequest' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/SearchResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: SearchRequest: properties: project_id: type: string format: uuid title: Project ID description: ID of the project to search within spec: $ref: '#/components/schemas/UserSearchSpec' title: Spec description: User-facing search spec to execute additionalProperties: false type: object required: - project_id - spec title: SearchRequest description: API request schema for end-user project search. SearchResponse: properties: assets: items: $ref: '#/components/schemas/SearchAssetResponse' type: array title: Search Results description: List of assets matching the search query type: object required: - assets title: SearchResponse description: Top-level response for project search. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError UserSearchSpec: properties: signals: items: $ref: '#/components/schemas/LogicalSignalQuery' type: array title: Signals description: Logical signal queries to execute filters: items: $ref: '#/components/schemas/Filter' type: array title: Filters description: Filters to apply to search results additionalProperties: false type: object required: - signals title: UserSearchSpec description: >- Executable user-facing search spec. Intent authoring may produce this type later, but intent-owned metadata such as source query, hint, rationale, and warnings must live outside this model. SearchAssetResponse: properties: is_symlink: type: boolean title: Is Symlink description: True when this item is a projected symlink default: false target_path: anyOf: - items: type: string type: array - type: 'null' title: Target Path description: Symlink target path components target_path_type: anyOf: - $ref: '#/components/schemas/SymlinkTargetPathType' - type: 'null' description: Symlink target path type target_resource_id: anyOf: - type: string format: uuid - type: 'null' title: Target Resource Id description: Resolved target resource ID target_resource_name: anyOf: - type: string - type: 'null' title: Target Resource Name description: Resolved target resource name target_resource_type: anyOf: - $ref: '#/components/schemas/ResourceType' - type: 'null' description: Resolved or hinted target resource type target_resolution_status: anyOf: - $ref: '#/components/schemas/SymlinkResolutionStatus' - type: 'null' description: Symlink resolution status id: type: string format: uuid title: Id type: $ref: '#/components/schemas/AssetType' description: Type of the asset (video, image, etc) name: type: string title: Name size_bytes: type: integer title: Size Bytes media: $ref: '#/components/schemas/AssetMedia' description: >- Intrinsic media properties (dimensions, duration, frame rate, timecode, page count) mime_type: type: string title: Mime Type save_original: type: boolean title: Save Original path: anyOf: - items: type: string type: array - type: 'null' title: Path description: Original file path for the asset (e.g., ['path', 'to', 'file.mov']) is_uploaded: type: boolean title: Is Uploaded is_generated: type: boolean title: Is Generated description: Whether this asset was produced by the AI generation pipeline default: false user_id: type: string format: uuid title: User Id workspace_id: type: string format: uuid title: Workspace Id description: ID of the workspace this asset belongs to project_id: type: string format: uuid title: Project Id description: ID of the project this asset belongs to parent_id: type: string format: uuid title: Parent Id description: ID of the parent resource (directory or project) actions: anyOf: - type: integer - type: 'null' title: Actions description: Action permission bitmap the caller holds on this asset comment_count: type: integer title: Comment Count description: Total number of visible comments on this asset, including replies stream_proxy: anyOf: - $ref: '#/components/schemas/ProxyDelivery' - $ref: '#/components/schemas/ProxyInfo' - type: 'null' title: Stream Proxy scrub_proxy: anyOf: - $ref: '#/components/schemas/ProxyDelivery' - $ref: '#/components/schemas/ProxyInfo' - type: 'null' title: Scrub Proxy audio_proxy: anyOf: - $ref: '#/components/schemas/ProxyDelivery' - $ref: '#/components/schemas/ProxyInfo' - type: 'null' title: Audio Proxy doc_proxy: anyOf: - $ref: '#/components/schemas/ProxyDelivery' - $ref: '#/components/schemas/ProxyInfo' - type: 'null' title: Doc Proxy scrub_preview: anyOf: - $ref: '#/components/schemas/PreviewDelivery' - $ref: '#/components/schemas/PreviewInfo' - type: 'null' title: Scrub Preview preview: anyOf: - $ref: '#/components/schemas/PreviewDelivery' - $ref: '#/components/schemas/PreviewInfo' - type: 'null' title: Preview custom_thumbnail: anyOf: - $ref: '#/components/schemas/SignedAttachment' - type: 'null' description: >- User-set custom thumbnail with a temporary URL. Overrides the generated preview when present. created_by_user: anyOf: - $ref: '#/components/schemas/UserInfo' - type: 'null' description: User who created this asset created_by_user_id: type: string format: uuid title: Created By User Id description: ID of the user that created the asset client_performed_at: anyOf: - type: string format: date-time - type: 'null' title: Client Performed At description: >- Server-recorded timestamp of the latest user action on this asset. NULL when no revision exists. version_stack_id: anyOf: - type: string format: uuid - type: 'null' title: Version Stack Id description: Version stack ID. NULL if not in a stack. version_number: anyOf: - type: integer - type: 'null' title: Version Number description: 1-indexed position in version stack. NULL if not in a stack. is_top_version: anyOf: - type: boolean - type: 'null' title: Is Top Version description: TRUE for top version in stack. NULL if not in a stack. revision_id: anyOf: - type: string format: uuid - type: 'null' title: Revision Id description: ID of the revision created by this operation (set on rename/move) is_latest: anyOf: - type: boolean - type: 'null' title: Is Latest description: Whether the revision is the overall latest (set on rename/move) manifest_id: anyOf: - type: string format: uuid - type: 'null' title: Manifest Id description: >- Content manifest of the current revision. NULL when the asset has no content yet. created: type: string format: date-time title: Created updated: type: string format: date-time title: Updated content_modified_at: type: string format: date-time title: Content Modified At description: >- Filesystem mtime: set at creation, advanced on content commits; unaffected by renames and metadata edits breadcrumb_path: items: type: string type: array title: Breadcrumb Path description: Directory breadcrumb segments for the asset search: $ref: '#/components/schemas/SearchAssetMetadata' title: Search description: Query-specific search metadata for the asset type: object required: - id - type - name - size_bytes - mime_type - save_original - is_uploaded - user_id - workspace_id - project_id - parent_id - comment_count - created_by_user_id - created - updated - content_modified_at - breadcrumb_path - search title: SearchAssetResponse description: >- Full asset response for search results — asset fields at top level, search metadata under 'search'. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError LogicalSignalQuery: properties: id: type: string title: ID description: Client-generated stable identifier for this signal query signal: $ref: '#/components/schemas/LogicalSignalType' title: Signal description: User-facing logical signal type to search query: type: string title: Query description: Text query for this logical signal type weight: anyOf: - type: number - type: 'null' title: Weight description: Optional per-signal weight additionalProperties: false type: object required: - id - signal - query title: LogicalSignalQuery description: 'One search signal: what to look for and where.' Filter: properties: id: type: string format: uuid title: Id description: UUID of the attribute to filter on clause: $ref: '#/components/schemas/FilterClause' description: Comparison operation (eq, neq, gt, lt, etc.) values: items: {} type: array title: Values description: Values to compare against (always a list) type: object required: - id - clause title: Filter description: Filter specification for filtering assets by attribute values. SymlinkTargetPathType: type: string enum: - relative - internal_absolute - external_absolute title: SymlinkTargetPathType ResourceType: type: string enum: - workspace - project - directory - asset - symlink - collection - canvas title: ResourceType description: Types of resources in the hierarchy. SymlinkResolutionStatus: type: string enum: - resolved - dangling - permission_denied - external title: SymlinkResolutionStatus AssetType: type: string enum: - video - image - audio - document - vector - other title: AssetType AssetMedia: properties: width: anyOf: - type: integer - type: 'null' title: Width description: Pixel width for visual assets. NULL when unknown. height: anyOf: - type: integer - type: 'null' title: Height description: Pixel height for visual assets. NULL when unknown. duration: anyOf: - type: number - type: 'null' title: Duration description: >- Duration in seconds for time-based assets. NULL for non-time-based assets. frame_rate: anyOf: - type: number - type: 'null' title: Frame Rate description: Frames per second for video assets. NULL for non-video assets. timecode: anyOf: - type: string - type: 'null' title: Timecode description: >- Source start timecode as HH:MM:SS:FF (HH:MM:SS;FF for drop-frame). NULL when the content carries none. page_count: anyOf: - type: integer - type: 'null' title: Page Count description: Number of pages for document assets. NULL for non-document assets. type: object title: AssetMedia description: Intrinsic media properties extracted from the asset's content. ProxyDelivery: properties: id: type: string format: uuid title: Id description: Resource identifier url: type: string title: Url description: Temporary URL for the upload or download url_expires_at: type: string format: date-time title: Url Expires At description: UTC datetime when the URL expires playback_mode: anyOf: - $ref: '#/components/schemas/AssetPlaybackMode' - type: 'null' description: >- How the returned proxy URL should be played. None means the URL is not stream playback media. size_bytes: anyOf: - type: integer - type: 'null' title: Size Bytes description: Size of the proxy file in bytes. type: object required: - id - url - url_expires_at title: ProxyDelivery description: Temporary URLs for playing a proxy. ProxyInfo: properties: id: type: string format: uuid title: Id type: object required: - id title: ProxyInfo description: A proxy identified by ID, without delivery URLs. PreviewDelivery: properties: id: type: string format: uuid title: Id description: Resource identifier url: type: string title: Url description: Temporary URL for the upload or download url_expires_at: type: string format: date-time title: Url Expires At description: UTC datetime when the URL expires scrub_metadata: anyOf: - $ref: '#/components/schemas/PreviewScrubMetadata' - type: 'null' description: Metadata for scrub preview sprite sheet size_bytes: anyOf: - type: integer - type: 'null' title: Size Bytes description: Size of the preview file in bytes. type: object required: - id - url - url_expires_at title: PreviewDelivery description: Temporary URLs for rendering a preview. PreviewInfo: properties: id: type: string format: uuid title: Id type: object required: - id title: PreviewInfo description: A preview identified by ID, without delivery URLs. SignedAttachment: properties: id: type: string format: uuid title: Id description: Resource identifier url: anyOf: - type: string - type: 'null' title: Url description: Temporary download URL url_expires_at: anyOf: - type: string format: date-time - type: 'null' title: Url Expires At description: When the URL expires user_id: anyOf: - type: string format: uuid - type: 'null' title: User Id description: User who uploaded. None if deleted. filename: type: string title: Filename description: Original filename mime_type: type: string title: Mime Type description: MIME type of the file size_bytes: type: integer title: Size Bytes description: File size in bytes uploaded: type: boolean title: Uploaded description: Whether the file has been uploaded created: type: string format: date-time title: Created description: Created timestamp updated: type: string format: date-time title: Updated description: Updated timestamp type: object required: - id - user_id - filename - mime_type - size_bytes - uploaded - created - updated title: SignedAttachment description: >- An attachment with a temporary download URL; url and url_expires_at are null until the upload is confirmed. UserInfo: properties: id: type: string format: uuid title: Id description: User ID first_name: type: string title: First Name description: User's first name last_name: type: string title: Last Name description: User's last name email: type: string title: Email description: User's email address avatar_url: anyOf: - type: string - type: 'null' title: Avatar Url description: User's avatar URL type: object required: - id - first_name - last_name - email title: UserInfo description: Lightweight user information for API responses SearchAssetMetadata: properties: score: type: number title: Score description: Ordering score across all signals used for result ranking moments: items: $ref: '#/components/schemas/SearchMoment' type: array title: Moments description: Typed local evidence moments for asset-level and timeline display confidence: $ref: '#/components/schemas/ConfidenceRating' title: Confidence description: >- Asset-level confidence rating derived from the best local evidence confidence signals: items: $ref: '#/components/schemas/SearchSignalSummary' type: array title: Signals description: Asset-level logical signals that contributed to this result type: object required: - score - confidence title: SearchAssetMetadata description: >- Search metadata for an asset — ordering score, moments, confidence, and matched signals. LogicalSignalType: type: string enum: - visual - transcript - document - filename title: LogicalSignalType description: Which content a search signal queries. FilterClause: type: string enum: - eq - neq - gt - lt - gte - lte - contains - not_contains - starts_with - ends_with - includes - not_includes - exists - not_exists - is_true - is_false title: FilterClause description: Comparison operations for filtering. AssetPlaybackMode: type: string enum: - mp4 - hls title: AssetPlaybackMode PreviewScrubMetadata: properties: frame_count: type: integer title: Frame Count width: type: integer title: Width height: type: integer title: Height frames_x: type: integer title: Frames X frames_y: type: integer title: Frames Y frame_width: type: integer title: Frame Width frame_height: type: integer title: Frame Height type: object required: - frame_count - width - height - frames_x - frames_y - frame_width - frame_height title: PreviewScrubMetadata SearchMoment: properties: id: type: string title: ID description: Stable evidence moment ID within this response kind: $ref: '#/components/schemas/SearchMomentKind' title: Kind description: Evidence moment kind for this moment confidence: $ref: '#/components/schemas/ConfidenceRating' title: Confidence description: Signal confidence rating for this evidence start_time: anyOf: - type: number - type: 'null' title: Start Time description: Start time in seconds when timeline-backed end_time: anyOf: - type: number - type: 'null' title: End Time description: End time in seconds when timeline-backed page: anyOf: - type: integer - type: 'null' title: Page description: 1-indexed source page when page-anchored (document moments) query: anyOf: - type: string - type: 'null' title: Query description: Signal query text when available preview: anyOf: - $ref: '#/components/schemas/PreviewInfo' - type: 'null' title: Preview description: Scene preview for this evidence moment evidence_text: anyOf: - $ref: '#/components/schemas/SearchEvidenceText' - type: 'null' title: Evidence Text description: Plain-text evidence excerpt for text-backed moments person: anyOf: - $ref: '#/components/schemas/SearchPersonEvidence' - type: 'null' title: Person description: Person evidence detail for person-kind moments type: object required: - id - kind - confidence title: SearchMoment description: |- Typed local evidence for search result display. Moments with timing fields are timeline evidence; moments without timing fields are asset-level evidence. ConfidenceRating: type: string enum: - unknown - low - medium - high title: ConfidenceRating description: Confidence rating for search result relevance. SearchSignalSummary: properties: kind: $ref: '#/components/schemas/SearchMomentKind' title: Kind description: Evidence moment kind confidence: $ref: '#/components/schemas/ConfidenceRating' title: Confidence description: Best confidence for this signal/query group moment_count: type: integer title: Moment Count description: Number of evidence moments for this signal/query group query: anyOf: - type: string - type: 'null' title: Query description: Signal query text when available type: object required: - kind - confidence - moment_count title: SearchSignalSummary description: Badge summary derived from resolved evidence moments. SearchMomentKind: type: string enum: - visual - transcript - document - filename - person title: SearchMomentKind description: Kinds of evidence a search result can carry. SearchEvidenceText: properties: source: $ref: '#/components/schemas/SearchEvidenceTextSource' title: Source description: Text source used for the evidence excerpt excerpt: type: string title: Excerpt description: Plain-text bounded excerpt from the matched source match_kind: $ref: '#/components/schemas/SearchEvidenceMatchKind' title: Match Kind description: Relationship between the query and excerpt type: object required: - source - excerpt - match_kind title: SearchEvidenceText description: Bounded plain-text evidence attached to text-backed search moments. SearchPersonEvidence: properties: person_id: type: string format: uuid title: Person ID description: Person represented by this person moment face_track_id: type: string format: uuid title: Face Track ID description: Face pointing at the person that backs this moment type: object required: - person_id - face_track_id title: SearchPersonEvidence description: Person evidence carried by person-kind search moments. SearchEvidenceTextSource: type: string enum: - transcription - document title: SearchEvidenceTextSource description: Trusted text source used for search moment evidence excerpts. SearchEvidenceMatchKind: type: string enum: - lexical - semantic title: SearchEvidenceMatchKind description: How the evidence excerpt relates to the user-facing signal query. securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: Aspect API key (sk_...) in Authorization header. 'Bearer ' optional. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.