Skip to content

Commit 25243f3

Browse files
Devesh-Skyflowclaude
Devesh-Skyflow
and
claude
committed
SK-2707: make response-object reference informative (types + descriptions)
Replace the flat "Attributes" column with a per-response subsection that documents each attribute's type and meaning, marks optional attributes with `| None`, and explains the shared `errors` shape once. Response anchors now come from the subsection headings (README deep-links still resolve). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent f060036 commit 25243f3

1 file changed

Lines changed: 127 additions & 18 deletions

File tree

‎docs/api_reference.md‎

Lines changed: 127 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -148,30 +148,139 @@ Wrapper for a file passed to `DeidentifyFileRequest`. Provide one of:
148148

149149
## Response objects
150150

151-
Every vault, token, connection, and Detect operation returns a typed response object. All carry an `errors` attribute that is populated on partial failure (`continue_on_error`).
152-
153-
| Response class | Module | Attributes |
154-
|----------------|--------|------------|
155-
| <a id="insertresponse"></a>`InsertResponse` | `skyflow.vault.data` | `inserted_fields`, `errors` |
156-
| <a id="getresponse"></a>`GetResponse` | `skyflow.vault.data` | `data`, `errors` |
157-
| <a id="deleteresponse"></a>`DeleteResponse` | `skyflow.vault.data` | `deleted_ids`, `errors` |
158-
| <a id="updateresponse"></a>`UpdateResponse` | `skyflow.vault.data` | `updated_field`, `errors` |
159-
| <a id="queryresponse"></a>`QueryResponse` | `skyflow.vault.data` | `fields`, `errors` |
160-
| <a id="fileuploadresponse"></a>`FileUploadResponse` | `skyflow.vault.data` | `skyflow_id`, `errors` |
161-
| <a id="detokenizeresponse"></a>`DetokenizeResponse` | `skyflow.vault.tokens` | `detokenized_fields`, `errors` |
162-
| <a id="tokenizeresponse"></a>`TokenizeResponse` | `skyflow.vault.tokens` | `tokenized_fields`, `errors` |
163-
| <a id="invokeconnectionresponse"></a>`InvokeConnectionResponse` | `skyflow.vault.connection` | `data`, `metadata`, `errors` |
164-
| <a id="deidentifytextresponse"></a>`DeidentifyTextResponse` | `skyflow.vault.detect` | `processed_text`, `entities`, `word_count`, `char_count`, `errors` |
165-
| <a id="reidentifytextresponse"></a>`ReidentifyTextResponse` | `skyflow.vault.detect` | `processed_text`, `errors` |
166-
| <a id="deidentifyfileresponse"></a>`DeidentifyFileResponse` | `skyflow.vault.detect` | `file_base64`, `file`, `type`, `extension`, `word_count`, `char_count`, `size_in_kb`, `duration_in_seconds`, `page_count`, `slide_count`, `entities`, `run_id`, `status`, `errors` |
151+
Every vault, token, connection, and Detect operation returns a typed response object. Each attribute below lists its type and meaning. Types use `| None` to mark attributes that may be absent.
152+
153+
> **The `errors` attribute** is common to most responses. It is `list[dict] | None` and is populated only on partial failure (for example when `continue_on_error=True`); it is `None` when there are no errors. Each error dict contains `request_index`, `request_id`, `error`, and `http_code`. The per-class tables below describe only the operation-specific attributes and refer back to this note for `errors`.
167154
168155
```python
169156
response = skyflow_client.vault('<VAULT_ID>').insert(insert_request)
170157
print(response.inserted_fields) # list of inserted records (with tokens if return_tokens=True)
171-
print(response.errors) # populated only on partial failure
158+
print(response.errors) # None unless there was a partial failure
172159
```
173160

174-
> `DeidentifyTextResponse.entities` is a list of [`EntityInfo`](#entityinfo). `DeidentifyFileResponse.file` is a [`File`](#file) wrapper.
161+
### `InsertResponse`
162+
163+
`skyflow.vault.data` — returned by `vault().insert()`.
164+
165+
| Attribute | Type | Description |
166+
|-----------|------|-------------|
167+
| `inserted_fields` | `list[dict]` | One entry per inserted record. Each has `skyflow_id`; with `return_tokens=True`, also a token per column; with `continue_on_error=True`, also a `request_index`. |
168+
| `errors` | `list[dict] \| None` | See the note above. |
169+
170+
### `GetResponse`
171+
172+
`skyflow.vault.data` — returned by `vault().get()`.
173+
174+
| Attribute | Type | Description |
175+
|-----------|------|-------------|
176+
| `data` | `list[dict]` | Retrieved records as `field → value` dicts (tokens instead of values when `return_tokens=True`). Defaults to `[]`. |
177+
| `errors` | `list[dict] \| None` | See the note above. |
178+
179+
### `DeleteResponse`
180+
181+
`skyflow.vault.data` — returned by `vault().delete()`.
182+
183+
| Attribute | Type | Description |
184+
|-----------|------|-------------|
185+
| `deleted_ids` | `list[str] \| None` | Skyflow IDs of the deleted records. |
186+
| `errors` | `list[dict] \| None` | See the note above. |
187+
188+
### `UpdateResponse`
189+
190+
`skyflow.vault.data` — returned by `vault().update()`.
191+
192+
| Attribute | Type | Description |
193+
|-----------|------|-------------|
194+
| `updated_field` | `dict` | The updated record: `skyflow_id`, plus a token per updated column when `return_tokens=True`. |
195+
| `errors` | `list[dict] \| None` | See the note above. |
196+
197+
### `QueryResponse`
198+
199+
`skyflow.vault.data` — returned by `vault().query()`.
200+
201+
| Attribute | Type | Description |
202+
|-----------|------|-------------|
203+
| `fields` | `list[dict]` | Matching records. Each record dict also includes a `tokenized_data` map. |
204+
| `errors` | `list[dict] \| None` | See the note above. |
205+
206+
### `FileUploadResponse`
207+
208+
`skyflow.vault.data` — returned by `vault().upload_file()`.
209+
210+
| Attribute | Type | Description |
211+
|-----------|------|-------------|
212+
| `skyflow_id` | `str` | ID of the record the file was attached to (or of the newly created record). |
213+
| `errors` | `list[dict] \| None` | See the note above. |
214+
215+
### `DetokenizeResponse`
216+
217+
`skyflow.vault.tokens` — returned by `vault().detokenize()`.
218+
219+
| Attribute | Type | Description |
220+
|-----------|------|-------------|
221+
| `detokenized_fields` | `list[dict]` | One entry per token, each with `token`, `value` (plaintext or masked), and `type` (the value type). |
222+
| `errors` | `list[dict] \| None` | See the note above. |
223+
224+
### `TokenizeResponse`
225+
226+
`skyflow.vault.tokens` — returned by `vault().tokenize()`.
227+
228+
| Attribute | Type | Description |
229+
|-----------|------|-------------|
230+
| `tokenized_fields` | `list[dict]` | One entry per value, each with its `token`. |
231+
| `errors` | `list[dict] \| None` | See the note above. |
232+
233+
### `InvokeConnectionResponse`
234+
235+
`skyflow.vault.connection` — returned by `connection().invoke()`.
236+
237+
| Attribute | Type | Description |
238+
|-----------|------|-------------|
239+
| `data` | `dict` | The connection's response body. |
240+
| `metadata` | `dict` | Response metadata (for example `request_id`). Defaults to `{}`. |
241+
| `errors` | `list[dict] \| None` | See the note above. |
242+
243+
### `DeidentifyTextResponse`
244+
245+
`skyflow.vault.detect` — returned by `detect().deidentify_text()`.
246+
247+
| Attribute | Type | Description |
248+
|-----------|------|-------------|
249+
| `processed_text` | `str` | The de-identified text. |
250+
| `entities` | `list[EntityInfo]` | Detected entities. See [`EntityInfo`](#entityinfo). |
251+
| `word_count` | `int` | Word count of the input text. |
252+
| `char_count` | `int` | Character count of the input text. |
253+
| `errors` | `list \| None` | See the note above. |
254+
255+
### `ReidentifyTextResponse`
256+
257+
`skyflow.vault.detect` — returned by `detect().reidentify_text()`.
258+
259+
| Attribute | Type | Description |
260+
|-----------|------|-------------|
261+
| `processed_text` | `str` | The re-identified text. |
262+
| `errors` | `list \| None` | See the note above. |
263+
264+
### `DeidentifyFileResponse`
265+
266+
`skyflow.vault.detect` — returned by `detect().deidentify_file()` and `detect().get_detect_run()`. All non-error attributes are optional (default `None`) and are populated based on the file type and processing status. If processing exceeds `wait_time`, only `run_id` and `status` are set; poll with `get_detect_run`.
267+
268+
| Attribute | Type | Description |
269+
|-----------|------|-------------|
270+
| `file_base64` | `str \| None` | The processed file as a base64 string. |
271+
| `file` | `File \| None` | The processed file wrapper. See [`File`](#file). |
272+
| `type` | `str \| None` | MIME type of the processed file. |
273+
| `extension` | `str \| None` | File extension of the processed file. |
274+
| `word_count` | `int \| None` | Word count (text-bearing files). |
275+
| `char_count` | `int \| None` | Character count (text-bearing files). |
276+
| `size_in_kb` | `float \| None` | Size of the processed file in KB. |
277+
| `duration_in_seconds` | `float \| None` | Duration in seconds (audio files). |
278+
| `page_count` | `int \| None` | Page count (PDF/document files). |
279+
| `slide_count` | `int \| None` | Slide count (presentation files). |
280+
| `entities` | `list[EntityInfo]` | Detected entities. Defaults to `[]`. See [`EntityInfo`](#entityinfo). |
281+
| `run_id` | `str \| None` | Run identifier; pass to `get_detect_run` to poll for results. |
282+
| `status` | `str \| None` | Processing status of the run. |
283+
| `errors` | `list \| None` | See the note above. |
175284

176285
---
177286

0 commit comments

Comments
 (0)