File Operations

Retrieve, download, and delete files.

Get File

Retrieve metadata for a specific file.

Endpoint

GET /v1/files/{file_id}

Example

curl https://api.gateflow.ai/v1/files/file-abc123 \
  -H "Authorization: Bearer gw_prod_..."

Python

import openai

client = openai.OpenAI(
    base_url="https://api.gateflow.ai/v1",
    api_key="gw_prod_..."
)

file = client.files.retrieve("file-abc123")

print(f"Filename: {file.filename}")
print(f"Size: {file.bytes} bytes")
print(f"Status: {file.status}")

Response

{
  "id": "file-abc123",
  "object": "file",
  "bytes": 1024000,
  "created_at": 1708099200,
  "filename": "document.pdf",
  "purpose": "document",
  "status": "processed",
  "status_details": null,
  "metadata": {
    "client": "acme",
    "type": "contract"
  }
}

Download File Content

Download the actual file content.

Endpoint

GET /v1/files/{file_id}/content

Example

curl https://api.gateflow.ai/v1/files/file-abc123/content \
  -H "Authorization: Bearer gw_prod_..." \
  --output document.pdf

Python

content = client.files.content("file-abc123")

with open("downloaded.pdf", "wb") as f:
    f.write(content.read())

Response

Returns the raw file content with appropriate Content-Type header.

Delete File

Delete a file from storage.

Endpoint

DELETE /v1/files/{file_id}

Example

curl -X DELETE https://api.gateflow.ai/v1/files/file-abc123 \
  -H "Authorization: Bearer gw_prod_..."

Python

result = client.files.delete("file-abc123")
print(f"Deleted: {result.deleted}")

Response

{
  "id": "file-abc123",
  "object": "file",
  "deleted": true
}

Get Processing Status

Check the processing status of a file.

Endpoint

GET /v1/files/{file_id}/status

Example

curl https://api.gateflow.ai/v1/files/file-abc123/status \
  -H "Authorization: Bearer gw_prod_..."

Response

{
  "id": "file-abc123",
  "status": "processed",
  "processing": {
    "started_at": 1708099200,
    "completed_at": 1708099215,
    "duration_ms": 15000,
    "stages": {
      "upload": "complete",
      "ocr": "complete",
      "chunking": "complete",
      "embedding": "complete",
      "pii_detection": "complete"
    }
  },
  "results": {
    "pages": 15,
    "chunks": 42,
    "characters": 45000,
    "pii_findings": 3,
    "classification": "confidential"
  }
}

Processing Stages

Stage	Description
upload	File uploaded to storage
ocr	Text extraction (documents)
transcription	Audio transcription
chunking	Text chunking for embeddings
embedding	Vector embedding generation
pii_detection	PII/PHI scanning
classification	Data classification

Get Extracted Text

Get the extracted text content from a processed document.

Endpoint

GET /v1/files/{file_id}/text

Example

curl https://api.gateflow.ai/v1/files/file-abc123/text \
  -H "Authorization: Bearer gw_prod_..."

Response

{
  "id": "file-abc123",
  "text": "This is the extracted text from the document...",
  "pages": [
    {"number": 1, "text": "Page 1 content..."},
    {"number": 2, "text": "Page 2 content..."}
  ],
  "metadata": {
    "total_pages": 15,
    "total_characters": 45000,
    "language": "en"
  }
}

Get Chunks

Get the text chunks created from a processed document.

Endpoint

GET /v1/files/{file_id}/chunks

Query Parameters

Parameter	Type	Description
limit	integer	Max chunks to return (default 20)
offset	integer	Offset for pagination

Example

curl "https://api.gateflow.ai/v1/files/file-abc123/chunks?limit=10" \
  -H "Authorization: Bearer gw_prod_..."

Response

{
  "id": "file-abc123",
  "total_chunks": 42,
  "chunks": [
    {
      "index": 0,
      "text": "This is the first chunk of text...",
      "page": 1,
      "start_char": 0,
      "end_char": 1000,
      "embedding_id": "emb_xyz789"
    },
    {
      "index": 1,
      "text": "This is the second chunk of text...",
      "page": 1,
      "start_char": 800,
      "end_char": 1800,
      "embedding_id": "emb_xyz790"
    }
  ]
}

Get PII Report

Get PII/PHI detection results for a processed file.

Endpoint

GET /v1/files/{file_id}/pii

Example

curl https://api.gateflow.ai/v1/files/file-abc123/pii \
  -H "Authorization: Bearer gw_prod_..."

Response

{
  "id": "file-abc123",
  "scan_completed_at": 1708099215,
  "total_findings": 3,
  "findings": [
    {
      "type": "person_name",
      "text": "John Smith",
      "location": {"page": 1, "start": 245, "end": 255},
      "confidence": 0.95,
      "redacted": false
    },
    {
      "type": "email",
      "text": "john@example.com",
      "location": {"page": 1, "start": 280, "end": 296},
      "confidence": 0.99,
      "redacted": false
    },
    {
      "type": "phone_number",
      "text": "+1-555-123-4567",
      "location": {"page": 2, "start": 100, "end": 115},
      "confidence": 0.92,
      "redacted": false
    }
  ],
  "summary": {
    "person_name": 1,
    "email": 1,
    "phone_number": 1
  }
}

Update File Metadata

Update custom metadata on a file.

Endpoint

PATCH /v1/files/{file_id}

Example

curl -X PATCH https://api.gateflow.ai/v1/files/file-abc123 \
  -H "Authorization: Bearer gw_prod_..." \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "client": "acme",
      "reviewed": true,
      "reviewer": "jane@company.com"
    }
  }'

Response

{
  "id": "file-abc123",
  "object": "file",
  "filename": "document.pdf",
  "metadata": {
    "client": "acme",
    "reviewed": true,
    "reviewer": "jane@company.com"
  }
}

Errors

Code	Description
400	Invalid request
401	Invalid API key
404	File not found
429	Rate limit exceeded

See Also

• Upload Files - Upload new files
• List Files - List all files
• Document Ingestion - Processing guide
• PII Detection - PII scanning