@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Vectara REST API
@base https://api.vectara.io
@version 1.0.0
@auth OAuth2 | ApiKey x-api-key in header
@common_fields {customer-id: int, timeout: str=30S}
@endpoints 29
@hint download_for_search
@toc compute-account-size(1), compute-corpus-size(1), create-api-key(1), create-corpus(1), delete-api-key(1), delete-conversations(1), delete-corpus(1), delete-doc(1), delete-turns(1), disable-turns(1), enable-api-key(1), get-usage-metrics(1), index(1), list-api-keys(1), list-conversations(1), list-corpora(1), list-documents(1), list-jobs(1), list-users(1), manage-user(1), query(1), read-conversations(1), read-corpus(1), replace-corpus-filter-attrs(1), reset-corpus(1), stream-query(1), update-corpus-enablement(1), core(1), upload(1)

@group compute-account-size
@endpoint POST /v1/compute-account-size
@returns(200) {size: [map], status: map{code: str, statusDetail: str}}

@endgroup

@group compute-corpus-size
@endpoint POST /v1/compute-corpus-size
@optional {corpusId: int(int64)}
@returns(200) {size: map{epochSecs: str(int64), size: str(uint64)}, status: map{code: str, statusDetail: str}}

@endgroup

@group create-api-key
@endpoint POST /v1/create-api-key
@optional {apiKeyData: [map{description: str, apiKeyType: str, corpusId: [int(int64)]}]}
@returns(200) {response: [map]}

@endgroup

@group create-corpus
@endpoint POST /v1/create-corpus
@optional {corpus: map{id: int(int64), name: str, description: str, dtProvision: str(int64), enabled: bool, swapQenc: bool, swapIenc: bool, textless: bool, encrypted: bool, encoderId: str(uint64), metadataMaxBytes: int(int64), customDimensions: [map], filterAttributes: [map]}}
@returns(200) {corpusId: int(int64), status: map{code: str, statusDetail: str}}

@endgroup

@group delete-api-key
@endpoint POST /v1/delete-api-key
@optional {keyId: [str]}
@returns(200) {status: [map]}

@endgroup

@group delete-conversations
@endpoint POST /v1/delete-conversations
@optional {conversationId: [str]}
@returns(200) {status: map{code: str, statusDetail: str}}

@endgroup

@group delete-corpus
@endpoint POST /v1/delete-corpus
@required {customerId: int(int64), corpusId: int(int64)}
@returns(200) {status: map{code: str, statusDetail: str}}

@endgroup

@group delete-doc
@endpoint POST /v1/delete-doc
@required {customerId: str(int64), corpusId: str(int64), documentId: str}
@returns(200)

@endgroup

@group delete-turns
@endpoint POST /v1/delete-turns
@optional {conversationId: str, turnId: str}
@returns(200) {status: map{code: str, statusDetail: str}}

@endgroup

@group disable-turns
@endpoint POST /v1/disable-turns
@optional {conversationId: str, turnId: str}
@returns(200) {status: map{code: str, statusDetail: str}}

@endgroup

@group enable-api-key
@endpoint POST /v1/enable-api-key
@optional {keyEnablement: [map{keyId: str, enable: bool}]}
@returns(200) {status: [map]}

@endgroup

@group get-usage-metrics
@endpoint POST /v1/get-usage-metrics
@optional {corpusId: int(int64), window: map{startEpochSecs: str(int64), endEpochSecs: str(int64)}, type: str(METRICTYPE__NONE/METRICTYPE__INDEXING/METRICTYPE__SERVING)=METRICTYPE__NONE, aggregationIntervalSecs: str(int64)}
@returns(200) {values: [map], status: map{code: str, statusDetail: str}}

@endgroup

@group index
@endpoint POST /v1/index
@required {customerId: str(int64), corpusId: str(int64), document: map{documentId: str, title: str, description: str, metadataJson: str, section: [map]}}
@returns(200) {status: map{code: str, statusDetail: str}, quotaConsumed: map{numChars: str(int64), numMetadataChars: str(int64)}}

@endgroup

@group list-api-keys
@endpoint POST /v1/list-api-keys
@optional {numResults: int(int64), pageKey: str(byte), apiKeyType: [str], readCorporaInfo: bool}
@returns(200) {keyData: [map], pageKey: str(byte), status: map{code: str, statusDetail: str}}

@endgroup

@group list-conversations
@endpoint POST /v1/list-conversations
@optional {numResults: int(int64), pageKey: str(byte)}
@returns(200) {conversation: [map], status: map{code: str, statusDetail: str}, pageKey: str(byte)}

@endgroup

@group list-corpora
@endpoint POST /v1/list-corpora
@required {numResults: int(int64)}
@optional {filter: str, pageKey: str(byte)}
@returns(200) {corpus: [map], pageKey: str(byte), status: map{code: str, statusDetail: str}}

@endgroup

@group list-documents
@endpoint POST /v1/list-documents
@optional {corpusId: int(int64), numResults: int(int64), pageKey: str(byte), metadataFilter: str}
@returns(200) {document: [map], nextPageKey: str(byte)}

@endgroup

@group list-jobs
@endpoint POST /v1/list-jobs
@optional {jobId: str, corpusId: [int(int64)], epochSecs: str(int64), state: [str], numResults: int(int64), pageKey: str(byte)}
@returns(200) {status: [map], job: [map], pageKey: str(byte)}

@endgroup

@group list-users
@endpoint POST /v1/list-users
@optional {listUsersType: str(LIST_USERS_TYPE__NONE/LIST_USERS_TYPE__CUSTOMER/LIST_USERS_TYPE__ALL)=LIST_USERS_TYPE__NONE, pageKey: str(byte), numResults: int(int64)}
@returns(200) {user: [map], pageKey: str(byte), status: map{code: str, statusDetail: str}}

@endgroup

@group manage-user
@endpoint POST /v1/manage-user
@optional {userAction: [map{user: map, userActionType: str}]}
@returns(200) {response: [map]}

@endgroup

@group query
@endpoint POST /v1/query
@required {query: [map{query: str, start: int(int64), numResults!: int(int64), contextConfig: map, corpusKey!: [map], summary: [map]}]}
@returns(200) {responseSet: [map], status: [map], metrics: map{queryEncodeMs: int(int64), retrievalMs: int(int64), userdataRetrievalMs: int(int64), rerankMs: int(int64)}}

@endgroup

@group read-conversations
@endpoint POST /v1/read-conversations
@optional {conversationId: [str]}
@returns(200) {Conversation: [map], status: map{code: str, statusDetail: str}}

@endgroup

@group read-corpus
@endpoint POST /v1/read-corpus
@optional {corpusId: [int(int64)], readBasicInfo: bool, readSize: bool, readApiKeys: bool, readCustomDimensions: bool, readFilterAttributes: bool}
@returns(200) {corpora: [map]}

@endgroup

@group replace-corpus-filter-attrs
@endpoint POST /v1/replace-corpus-filter-attrs
@optional {corpusId: int(int64), filterAttributes: [map{name: str, description: str, indexed: bool, type: str, level: str}]}
@returns(200) {status: map{code: str, statusDetail: str}, jobId: str}

@endgroup

@group reset-corpus
@endpoint POST /v1/reset-corpus
@required {customerId: int(int64), corpusId: int(int64)}
@returns(200) {status: map{code: str, statusDetail: str}}

@endgroup

@group stream-query
@endpoint POST /v1/stream-query
@required {query: [map{query: str, start: int(int64), numResults!: int(int64), contextConfig: map, corpusKey!: [map], summary: [map]}]}
@returns(200) {result: map{batchQueryResponse: map{responseSet: [map], status: [map], metrics: map{queryEncodeMs: int(int64), retrievalMs: int(int64), userdataRetrievalMs: int(int64), rerankMs: int(int64)}}, responseSet: map{response: [map], status: [map], document: [map], summary: [map], futureId: int(int32)}, summary: map{text: str, lang: str, chat: map{conversationId: str, turnId: str, status: map}, factualConsistency: map{score: num(float), status: map}, done: bool, status: [map], futureId: int(int32)}, status: [map]}, error: map{code: int(int32), message: str, details: [map]}}

@endgroup

@group update-corpus-enablement
@endpoint POST /v1/update-corpus-enablement
@optional {corpusId: int(int64), enable: bool}
@returns(200) {status: map{code: str, statusDetail: str}}

@endgroup

@group core
@endpoint POST /v1/core/index
@optional {customerId: str(int64), corpusId: str(int64), document: map{documentId: str, metadataJson: str, parts: [map], defaultPartContext: str, customDims: [map]}}
@returns(200) {status: map{code: str, statusDetail: str}, quotaConsumed: map{numChars: str(int64), numMetadataChars: str(int64)}}

@endgroup

@group upload
@endpoint POST /v1/upload
@required {c: int, o: int}
@optional {d: bool}
@returns(200) {response: map{status: map, quotaConsumed: map{numChars: str, numMetadataChars: str}}}
@errors {400, 401, 403, 409, 507}

@endgroup

@end