Skip to Content
AdvancedArtifact Management

Artifact Management (API)

Base Path: /api/v1/artifacts

GET / - List Artifacts

  • Description: Lists all artifacts for the user with pagination and filtering.
  • Credit Cost: 1
  • Parameters (query):
    • status (string, optional): Filter by status (e.g., “processing”, “ready”, “failed”).
    • limit (integer, optional, default: 10, max: 100): Number of artifacts per page.
    • page (integer, optional, default: 1): Page number.
  • Use Case: Populate a dashboard in your application that shows a user all the files they have previously uploaded.
make_api_request("GET", "/artifacts", params={"status": "ready", "limit": 10})
  • Success Response (200 OK): 
    {
  "artifacts": [
    {
      "id": "art_12345678-1234-1234-1234-123456789abc",
      "filename": "document.pdf",
      "status": "ready",
      "size_bytes": 102400,
      "upload_date": "2025-09-30T10:00:00Z",
      "content_type": "application/pdf"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 50,
    "pages": 5
  },
  "credits_consumed": 1
}

GET /search - Search Artifacts

  • Description: Provides advanced search for a user’s artifacts.
  • Credit Cost: 2
  • Parameters (query):
    • q (string, required): Search query (filename, metadata, or content keywords).
    • limit (integer, optional, default: 10): Number of results.
  • Use Case: Implement a search bar in your application that allows users to find specific documents by filename, content hash, or upload date.
make_api_request("GET", "/artifacts/search", params={"q": "invoice"})
  • Success Response (200 OK): 
    {
  "results": [
    {
      "id": "art_87654321-4321-4321-4321-cba987654321",
      "filename": "invoice_2025.pdf",
      "relevance_score": 0.95,
      "snippet": "Invoice #INV-123 for services rendered."
    }
  ],
  "total": 3,
  "credits_consumed": 2
}

GET {artifact_id} - Get Artifact Details

  • Description: Retrieves all metadata and job history for a specific artifact.
  • Credit Cost: 1
  • Path Parameters:
    • artifact_id (string, required): The unique ID of the artifact.
  • Use Case: Display a detailed view of a selected file, showing its status, type, size, and a history of all processing jobs performed on it.
ARTIFACT_ID = "art_12345678-1234-1234-1234-123456789abc"
make_api_request("GET", f"/artifacts/{ARTIFACT_ID}")
  • Success Response (200 OK): 
    {
  "artifact": {
    "id": "art_12345678-1234-1234-1234-123456789abc",
    "filename": "document.pdf",
    "status": "ready",
    "size_bytes": 102400,
    "upload_date": "2025-09-30T10:00:00Z",
    "content_type": "application/pdf",
    "metadata": {
      "description": "Sample invoice"
    },
    "job_history": [
      {
        "job_id": "job_abc123",
        "type": "extraction",
        "status": "completed",
        "timestamp": "2025-09-30T10:05:00Z"
      }
    ]
  },
  "credits_consumed": 1
}

PATCH {artifact_id} - Update Artifact Metadata

  • Description: Updates an artifact’s mutable metadata.
  • Credit Cost: 1
  • Path Parameters:
    • artifact_id (string, required): The unique ID of the artifact.
  • Request Body:
    • description (string, optional): Updated description.
    • tags (array of strings, optional): Updated tags.
  • Use Case: Allow users to rename their uploaded files or add descriptive notes for better organization within your application.
ARTIFACT_ID = "art_12345678-1234-1234-1234-123456789abc"
make_api_request("PATCH", f"/artifacts/{ARTIFACT_ID}", json_payload={"description": "New description."})
  • Success Response (200 OK): 
    {
  "updated_artifact": {
    "id": "art_12345678-1234-1234-1234-123456789abc",
    "description": "New description."
  },
  "credits_consumed": 1
}

DELETE {artifact_id} - Delete Artifact

  • Description: Deletes an artifact and its associated data.
  • Credit Cost: 2
  • Path Parameters:
    • artifact_id (string, required): The unique ID of the artifact.
  • Use Case: Provide a “delete” button for users to permanently remove their files and associated data from the system.
ARTIFACT_ID = "art_12345678-1234-1234-1234-123456789abc"
make_api_request("DELETE", f"/artifacts/{ARTIFACT_ID}")
  • Success Response (204 No Content)

POST /upload - Upload a Single File

  • Description: Uploads a single file directly and begins processing.
  • Credit Cost: 5 (includes initial upload and processing start)
  • Parameters (multipart/form-data):
    • file (file, required): The file to upload (supports PDF, DOCX, images, etc.).
  • Use Case: The primary method for getting user files into the DataDistill system for further processing and extraction.
with open("path/to/doc.pdf", "rb") as f:
    files = {"file": ("doc.pdf", f, "application/pdf")}
    make_api_request("POST", "/artifacts/upload", files=files)
  • Success Response (201 Created): 
    {
  "artifact": {
    "id": "art_12345678-1234-1234-1234-123456789abc",
    "filename": "doc.pdf",
    "status": "processing",
    "upload_date": "2025-09-30T10:00:00Z"
  },
  "credits_consumed": 5
}

POST {artifact_id}/cancel - Cancel Artifact Processing

  • Description: Cancels an artifact stuck in the ‘processing’ state.
  • Credit Cost: 1 (partial refund may apply for unused processing)
  • Path Parameters:
    • artifact_id (string, required): The unique ID of the artifact.
  • Use Case: Provide a way for users or administrators to stop a processing job that seems to be taking too long, preventing it from consuming further resources.
ARTIFACT_ID = "art_12345678-1234-1234-1234-123456789abc"
make_api_request("POST", f"/artifacts/{ARTIFACT_ID}/cancel")
  • Success Response (200 OK): 
    {
  "status": "cancelled",
  "message": "Processing job has been cancelled.",
  "credits_consumed": 1,
  "refunded_credits": 2
}
Advanced TopicsText Processing API