Package ai.vectros.resources.documents

Class DocumentsClient

java.lang.Object
ai.vectros.resources.documents.DocumentsClient
public class DocumentsClient extends Object

  • Field Details

  • Constructor Details

    • DocumentsClient

      public DocumentsClient(ClientOptions clientOptions)

  • Method Details

    • withRawResponse

      public RawDocumentsClient withRawResponse()
      Get responses with HTTP metadata like headers

    • listDocuments

      public DocumentPage listDocuments()
      Returns a paginated list of your documents, optionally filtered by folder (folderId) and/or owner (userId or scope). The response is a {data, nextCursor} envelope; pass nextCursor back as startFrom to fetch the next page. Requires the documents:r scope.

    • listDocuments

      public DocumentPage listDocuments(RequestOptions requestOptions)
      Returns a paginated list of your documents, optionally filtered by folder (folderId) and/or owner (userId or scope). The response is a {data, nextCursor} envelope; pass nextCursor back as startFrom to fetch the next page. Requires the documents:r scope.

    • listDocuments

      public DocumentPage listDocuments(ListDocumentsRequest request)
      Returns a paginated list of your documents, optionally filtered by folder (folderId) and/or owner (userId or scope). The response is a {data, nextCursor} envelope; pass nextCursor back as startFrom to fetch the next page. Requires the documents:r scope.

    • listDocuments

      public DocumentPage listDocuments(ListDocumentsRequest request, RequestOptions requestOptions)
      Returns a paginated list of your documents, optionally filtered by folder (folderId) and/or owner (userId or scope). The response is a {data, nextCursor} envelope; pass nextCursor back as startFrom to fetch the next page. Requires the documents:r scope.

    • ingestDocument

      public DocumentResponse ingestDocument(DocumentRequest body)
      Creates a document from a raw text string and queues it for asynchronous indexing so it becomes searchable. Optionally supply an externalId to make the create idempotent — if a document with the same externalId already exists in your context, that existing document is returned unchanged instead of a duplicate being created. The response's created field (and the HTTP status — 201 when created, 200 when an existing document was returned) tells the two apart. To overwrite an existing document's content instead of returning it unchanged, set ?upsert=true (this also requires the documents:u scope). Requires the documents:c scope to create. Being returned the existing document on a collision is a read of that document's data and additionally requires the documents:r scope — a credential holding documents:c alone receives a 400 ("already exists") on collision instead of the document.

    • ingestDocument

      public DocumentResponse ingestDocument(DocumentRequest body, RequestOptions requestOptions)
      Creates a document from a raw text string and queues it for asynchronous indexing so it becomes searchable. Optionally supply an externalId to make the create idempotent — if a document with the same externalId already exists in your context, that existing document is returned unchanged instead of a duplicate being created. The response's created field (and the HTTP status — 201 when created, 200 when an existing document was returned) tells the two apart. To overwrite an existing document's content instead of returning it unchanged, set ?upsert=true (this also requires the documents:u scope). Requires the documents:c scope to create. Being returned the existing document on a collision is a read of that document's data and additionally requires the documents:r scope — a credential holding documents:c alone receives a 400 ("already exists") on collision instead of the document.

    • ingestDocument

      public DocumentResponse ingestDocument(IngestDocumentRequest request)
      Creates a document from a raw text string and queues it for asynchronous indexing so it becomes searchable. Optionally supply an externalId to make the create idempotent — if a document with the same externalId already exists in your context, that existing document is returned unchanged instead of a duplicate being created. The response's created field (and the HTTP status — 201 when created, 200 when an existing document was returned) tells the two apart. To overwrite an existing document's content instead of returning it unchanged, set ?upsert=true (this also requires the documents:u scope). Requires the documents:c scope to create. Being returned the existing document on a collision is a read of that document's data and additionally requires the documents:r scope — a credential holding documents:c alone receives a 400 ("already exists") on collision instead of the document.

    • ingestDocument

      public DocumentResponse ingestDocument(IngestDocumentRequest request, RequestOptions requestOptions)
      Creates a document from a raw text string and queues it for asynchronous indexing so it becomes searchable. Optionally supply an externalId to make the create idempotent — if a document with the same externalId already exists in your context, that existing document is returned unchanged instead of a duplicate being created. The response's created field (and the HTTP status — 201 when created, 200 when an existing document was returned) tells the two apart. To overwrite an existing document's content instead of returning it unchanged, set ?upsert=true (this also requires the documents:u scope). Requires the documents:c scope to create. Being returned the existing document on a collision is a read of that document's data and additionally requires the documents:r scope — a credential holding documents:c alone receives a 400 ("already exists") on collision instead of the document.

    • getDocument

      public DocumentResponse getDocument(String id)
      Returns a single document by its ID, including its full structured payload. Requires the documents:r scope.

    • getDocument

      public DocumentResponse getDocument(String id, RequestOptions requestOptions)
      Returns a single document by its ID, including its full structured payload. Requires the documents:r scope.

    • getDocument

      public DocumentResponse getDocument(String id, GetDocumentRequest request)
      Returns a single document by its ID, including its full structured payload. Requires the documents:r scope.

    • getDocument

      public DocumentResponse getDocument(String id, GetDocumentRequest request, RequestOptions requestOptions)
      Returns a single document by its ID, including its full structured payload. Requires the documents:r scope.

    • updateDocument

      public DocumentResponse updateDocument(String id, DocumentRequest body)
      Replaces the mutable fields of a document. This is a full replacement of the payload — to merge fields instead, use PATCH. If you supply new text, the document body is re-ingested and re-queued for indexing. Requires the documents:u scope.

    • updateDocument

      public DocumentResponse updateDocument(String id, DocumentRequest body, RequestOptions requestOptions)
      Replaces the mutable fields of a document. This is a full replacement of the payload — to merge fields instead, use PATCH. If you supply new text, the document body is re-ingested and re-queued for indexing. Requires the documents:u scope.

    • updateDocument

      public DocumentResponse updateDocument(String id, UpdateDocumentRequest request)
      Replaces the mutable fields of a document. This is a full replacement of the payload — to merge fields instead, use PATCH. If you supply new text, the document body is re-ingested and re-queued for indexing. Requires the documents:u scope.

    • updateDocument

      public DocumentResponse updateDocument(String id, UpdateDocumentRequest request, RequestOptions requestOptions)
      Replaces the mutable fields of a document. This is a full replacement of the payload — to merge fields instead, use PATCH. If you supply new text, the document body is re-ingested and re-queued for indexing. Requires the documents:u scope.

    • deleteDocument

      public void deleteDocument(String id)
      Permanently deletes the document and removes it from the search index. This cannot be undone. Requires the documents:d scope.

    • deleteDocument

      public void deleteDocument(String id, RequestOptions requestOptions)
      Permanently deletes the document and removes it from the search index. This cannot be undone. Requires the documents:d scope.

    • deleteDocument

      public void deleteDocument(String id, DeleteDocumentRequest request)
      Permanently deletes the document and removes it from the search index. This cannot be undone. Requires the documents:d scope.

    • deleteDocument

      public void deleteDocument(String id, DeleteDocumentRequest request, RequestOptions requestOptions)
      Permanently deletes the document and removes it from the search index. This cannot be undone. Requires the documents:d scope.

    • patchDocument

      public DocumentResponse patchDocument(String id, PatchDocumentRequest request)
      Partially updates a document using an RFC 7386 JSON Merge Patch. The payload object is deep-merged: keys you send overwrite existing values (recursing into nested objects), a key set to null is deleted, and keys you omit are preserved — unlike PUT, which replaces the whole payload. Top-level fields (title, folderId, schemaId, ownership) are set when present and left unchanged when omitted; sending a top-level field as null is rejected. Supplying text re-ingests the document body (same as PUT). indexMode, externalId, and storeText (text retention is fixed at ingest) are immutable and rejected if present. The merged result is validated against the bound schema. Pass expectedVersion for optimistic concurrency (409 on conflict). Requires the documents:u scope.

    • patchDocument

      public DocumentResponse patchDocument(String id, PatchDocumentRequest request, RequestOptions requestOptions)
      Partially updates a document using an RFC 7386 JSON Merge Patch. The payload object is deep-merged: keys you send overwrite existing values (recursing into nested objects), a key set to null is deleted, and keys you omit are preserved — unlike PUT, which replaces the whole payload. Top-level fields (title, folderId, schemaId, ownership) are set when present and left unchanged when omitted; sending a top-level field as null is rejected. Supplying text re-ingests the document body (same as PUT). indexMode, externalId, and storeText (text retention is fixed at ingest) are immutable and rejected if present. The merged result is validated against the bound schema. Pass expectedVersion for optimistic concurrency (409 on conflict). Requires the documents:u scope.

    • lookupDocuments

      public DocumentLookupPage lookupDocuments(LookupDocumentsRequest request)
      Finds documents of a given type by field value. Supported fields: externalId (the document's first-class external identifier — no schema declaration required) and any field declared as a lookup field on the bound schema. A lookup on a sensitive field is rejected here because the value would appear in the URL query string; use POST /v1/documents/lookup (the request-body variant) for a sensitive field instead. type's schema resolves with basedOn-aware shadowing: your own userId- or scope-owned variant if you have one, otherwise the shared base — for a scoped credential the owner is always your own token identity; userId/scope here only apply as an explicit owner selector for a root API key. Results are paginated: set limit for the page size and feed the returned nextCursor back as startFrom to fetch the next page. The response is a {data, nextCursor} envelope. Requires the documents:r scope.

    • lookupDocuments

      public DocumentLookupPage lookupDocuments(LookupDocumentsRequest request, RequestOptions requestOptions)
      Finds documents of a given type by field value. Supported fields: externalId (the document's first-class external identifier — no schema declaration required) and any field declared as a lookup field on the bound schema. A lookup on a sensitive field is rejected here because the value would appear in the URL query string; use POST /v1/documents/lookup (the request-body variant) for a sensitive field instead. type's schema resolves with basedOn-aware shadowing: your own userId- or scope-owned variant if you have one, otherwise the shared base — for a scoped credential the owner is always your own token identity; userId/scope here only apply as an explicit owner selector for a root API key. Results are paginated: set limit for the page size and feed the returned nextCursor back as startFrom to fetch the next page. The response is a {data, nextCursor} envelope. Requires the documents:r scope.

    • lookupDocumentsByBody

      public DocumentLookupPage lookupDocumentsByBody(DocumentLookupRequest request)
      Request-body equivalent of GET /v1/documents/lookup. Use this when looking up by a sensitive field: the value travels in the request body (and is blind-indexed server-side) instead of the URL query string, so it never lands in access, CDN, or proxy logs. The GET variant rejects value for a sensitive field and directs you here. Requires the documents:r scope.

    • lookupDocumentsByBody

      public DocumentLookupPage lookupDocumentsByBody(DocumentLookupRequest request, RequestOptions requestOptions)
      Request-body equivalent of GET /v1/documents/lookup. Use this when looking up by a sensitive field: the value travels in the request body (and is blind-indexed server-side) instead of the URL query string, so it never lands in access, CDN, or proxy logs. The GET variant rejects value for a sensitive field and directs you here. Requires the documents:r scope.

    • getDocumentDownloadUrl

      public DocumentDownloadResponse getDocumentDownloadUrl(String id)
      Returns a short-lived presigned S3 GET URL for the original uploaded file. Only available for file-backed documents (created via POST /v1/documents/upload); text-only documents return 400. Requires the documents:r scope.

    • getDocumentDownloadUrl

      public DocumentDownloadResponse getDocumentDownloadUrl(String id, RequestOptions requestOptions)
      Returns a short-lived presigned S3 GET URL for the original uploaded file. Only available for file-backed documents (created via POST /v1/documents/upload); text-only documents return 400. Requires the documents:r scope.

    • getDocumentDownloadUrl

      public DocumentDownloadResponse getDocumentDownloadUrl(String id, GetDocumentDownloadUrlRequest request)
      Returns a short-lived presigned S3 GET URL for the original uploaded file. Only available for file-backed documents (created via POST /v1/documents/upload); text-only documents return 400. Requires the documents:r scope.

    • getDocumentDownloadUrl

      public DocumentDownloadResponse getDocumentDownloadUrl(String id, GetDocumentDownloadUrlRequest request, RequestOptions requestOptions)
      Returns a short-lived presigned S3 GET URL for the original uploaded file. Only available for file-backed documents (created via POST /v1/documents/upload); text-only documents return 400. Requires the documents:r scope.

    • getDocumentText

      public DocumentTextResponse getDocumentText(String id)
      Returns the document's full text body when it is retained: always available for text-ingested documents, and for file-uploaded documents unless they were uploaded with storeText=false (which discards the extracted text once indexing completes — the original file remains available via GET /{id}/download). Returns 404 when the document does not exist, its text was not retained, or extraction has not yet completed. Requires the documents:r scope.

    • getDocumentText

      public DocumentTextResponse getDocumentText(String id, RequestOptions requestOptions)
      Returns the document's full text body when it is retained: always available for text-ingested documents, and for file-uploaded documents unless they were uploaded with storeText=false (which discards the extracted text once indexing completes — the original file remains available via GET /{id}/download). Returns 404 when the document does not exist, its text was not retained, or extraction has not yet completed. Requires the documents:r scope.

    • getDocumentText

      public DocumentTextResponse getDocumentText(String id, GetDocumentTextRequest request)
      Returns the document's full text body when it is retained: always available for text-ingested documents, and for file-uploaded documents unless they were uploaded with storeText=false (which discards the extracted text once indexing completes — the original file remains available via GET /{id}/download). Returns 404 when the document does not exist, its text was not retained, or extraction has not yet completed. Requires the documents:r scope.

    • getDocumentText

      public DocumentTextResponse getDocumentText(String id, GetDocumentTextRequest request, RequestOptions requestOptions)
      Returns the document's full text body when it is retained: always available for text-ingested documents, and for file-uploaded documents unless they were uploaded with storeText=false (which discards the extracted text once indexing completes — the original file remains available via GET /{id}/download). Returns 404 when the document does not exist, its text was not retained, or extraction has not yet completed. Requires the documents:r scope.

    • getDocumentVersions

      public ModelDataVersionPage getDocumentVersions(String id)
      Returns the audit trail of changes (CREATE, UPDATE, DELETE) for a document. History is recorded only for documents bound to a schema that has audit history enabled (the default for typed documents); untyped documents have no version history. The response is a {data, nextCursor} envelope. Requires the documents:r scope.

    • getDocumentVersions

      public ModelDataVersionPage getDocumentVersions(String id, RequestOptions requestOptions)
      Returns the audit trail of changes (CREATE, UPDATE, DELETE) for a document. History is recorded only for documents bound to a schema that has audit history enabled (the default for typed documents); untyped documents have no version history. The response is a {data, nextCursor} envelope. Requires the documents:r scope.

    • getDocumentVersions

      public ModelDataVersionPage getDocumentVersions(String id, GetDocumentVersionsRequest request)
      Returns the audit trail of changes (CREATE, UPDATE, DELETE) for a document. History is recorded only for documents bound to a schema that has audit history enabled (the default for typed documents); untyped documents have no version history. The response is a {data, nextCursor} envelope. Requires the documents:r scope.

    • getDocumentVersions

      public ModelDataVersionPage getDocumentVersions(String id, GetDocumentVersionsRequest request, RequestOptions requestOptions)
      Returns the audit trail of changes (CREATE, UPDATE, DELETE) for a document. History is recorded only for documents bound to a schema that has audit history enabled (the default for typed documents); untyped documents have no version history. The response is a {data, nextCursor} envelope. Requires the documents:r scope.

    • uploadDocument

      public FileUploadResponse uploadDocument(FileUploadRequest request)
      Starts a file-based document by returning a short-lived presigned S3 PUT URL. Upload the file bytes directly to uploadUrl; the document is then automatically queued for text extraction and asynchronous indexing. Supplying an externalId makes this idempotent — re-initiating an upload with the same externalId re-issues a fresh presigned URL to the SAME existing document/object (so a re-upload inherently replaces the file body) rather than creating a duplicate. The response's created field (and the HTTP status — 201 when a new document was minted, 200 when an existing one was matched) tells the two apart. With ?upsert=true, the submitted payload/title are also applied to the matched document (file-body divergence cannot be diffed at upload-init — the bytes have not arrived yet — so the re-upload itself replaces the body). Creating a NEW document requires the documents:c scope. Re-uploading over an EXISTING document overwrites (and re-indexes) its body, so it is an update: it requires the documents:u scope (as does ?upsert=true for the metadata).

    • uploadDocument

      public FileUploadResponse uploadDocument(FileUploadRequest request, RequestOptions requestOptions)
      Starts a file-based document by returning a short-lived presigned S3 PUT URL. Upload the file bytes directly to uploadUrl; the document is then automatically queued for text extraction and asynchronous indexing. Supplying an externalId makes this idempotent — re-initiating an upload with the same externalId re-issues a fresh presigned URL to the SAME existing document/object (so a re-upload inherently replaces the file body) rather than creating a duplicate. The response's created field (and the HTTP status — 201 when a new document was minted, 200 when an existing one was matched) tells the two apart. With ?upsert=true, the submitted payload/title are also applied to the matched document (file-body divergence cannot be diffed at upload-init — the bytes have not arrived yet — so the re-upload itself replaces the body). Creating a NEW document requires the documents:c scope. Re-uploading over an EXISTING document overwrites (and re-indexes) its body, so it is an update: it requires the documents:u scope (as does ?upsert=true for the metadata).