Skip to main content

​
Overview

After uploading a file via TUS, you can call any API endpoint that supports post-upload processing. The same delegation token used for the upload authenticates the processing request.
This endpoint pattern replaces the previous webhook-based flow. Your frontend now calls processing endpoints directly after upload, giving you immediate control over when processing occurs.

​
Authentication

Use the same delegation token that was used for the TUS upload: 
Authorization: Bearer <delegation_token>
The token contains the merchant_id used for billing, so no additional authentication is required.

​
Processing Flow

1

Upload Complete

After the TUS upload completes, your frontend receives the file URL.
2

Call Processing Endpoint

Your frontend sends a POST request with the file URL and delegation token to any supported endpoint.
3

Internal Fetch

The API fetches the file from storage using the provided URL.
4

Parsing

The parser extracts structured data from the uploaded file.
5

Usage Recording

Usage is recorded against the merchant’s ledger (from the JWT). See Usage & Billing.
6

Processing

The endpoint processes the extracted data (validation, classification, enrichment, etc.).
7

Response

Processed data and usage information are returned directly to your frontend.

​
Discovering Available Endpoints

Use the route discovery endpoint to find all endpoints that support post-upload processing: 
curl https://api.superseeded.ai/v1/routes/from-upload
Response: 
{
  "routes": [
    {
      "id": "verify-plant-names",
      "name": "Verify Plant Names",
      "description": "Verify botanical plant names are correct and spelled properly",
      "endpoint": "/v1/verify/plant-names",
      "method": "POST",
      "requires_auth": true,
      "accepted_file_types": [".json", ".xlsx", ".xls", ".csv", ".txt", ".pdf"],
      "category": "verification"
    },
    {
      "id": "validate-pot-sizes",
      "name": "Validate Pot Sizes",
      "description": "Classify pot sizes and plant specifications into Growth Equivalent categories",
      "endpoint": "/v1/verify/pot-sizes",
      "method": "POST",
      "requires_auth": true,
      "accepted_file_types": [".json", ".xlsx", ".xls", ".pdf", ".txt", ".png", ".jpg", ".jpeg", ".gif", ".webp"],
      "category": "enrichment"
    }
  ],
  "version": "1.0"
}

​
Example: Species Name Validation

This example shows how to validate botanical names from an uploaded file.

​
Request

Headers:
HeaderValueDescription
AuthorizationBearer <token>The delegation token from /v1/auth/delegate-upload
Content-Typeapplication/jsonRequired for JSON body
Request Body:
FieldTypeRequiredDescription
file_urlstringYesThe TUS upload URL returned after upload completes
filenamestringNoOriginal filename for context

​
Example Request

curl -X POST https://api.superseeded.ai/v1/verify/plant-names \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://secure.superseeded.ai/files/abc123",
    "filename": "plant_schedule.xlsx"
  }'

​
Example Response

{
  "results": [
    {
      "query": {
        "submitted_name": "Eucalyptus globulus",
        "normalized_name": "eucalyptus globulus",
        "query_timestamp": "2025-01-15T10:30:00Z"
      },
      "validation": {
        "status": "validated",
        "confidence": "high",
        "consensus_score": 0.98,
        "sources_checked": 11,
        "sources_matched": 9
      },
      "accepted_name": {
        "scientific_name": "Eucalyptus globulus",
        "author": "Labill.",
        "nomenclatural_status": "accepted",
        "common_names": [
          {
            "name": "Tasmanian Blue Gum",
            "language": "en",
            "region": "Global"
          }
        ],
        "taxonomic_rank": "species"
      },
      "taxonomy": {
        "kingdom": "Plantae",
        "family": "Myrtaceae",
        "genus": "Eucalyptus",
        "species": "globulus"
      },
      "cross_references": {
        "gbif_id": "3176787",
        "wfo_id": "946382",
        "powo_id": "urn:lsid:ipni.org:names:30001419-2"
      }
    }
  ],
  "summary": {
    "total": 1,
    "validated": 1,
    "uncertain": 0,
    "not_found": 0
  }
}

​
Example: Pot Size Validation

This example shows how to classify pot sizes from an uploaded file.

​
Request

curl -X POST https://api.superseeded.ai/v1/verify/pot-sizes \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://secure.superseeded.ai/files/abc123",
    "filename": "inventory.xlsx"
  }'

​
Response

{
  "results": [
    {
      "input_label": "400mm AS",
      "match_confidence": "High",
      "standard_data": {
        "id": "4.1",
        "type": "Pot - Air Pruning",
        "stage_order": 4,
        "stage_name": "Advanced Production",
        "is_biological": true,
        "logistics": {
          "tier": "Pallet",
          "is_stackable": false,
          "freight_efficiency": "Medium"
        }
      }
    }
  ]
}

​
Error Responses

StatusErrorDescription
400invalid_requestMissing file_url in request body
401invalid_tokenJWT token validation failed or expired
403forbiddenToken doesn’t have access to the specified file
404file_not_foundThe specified file URL does not exist
422parsing_failedCould not extract data from file
500processing_errorProcessing service unavailable

​
Token Reuse

The delegation token serves dual purposes:
  1. Upload authentication — Authorizes the TUS upload
  2. Processing authentication — Authorizes processing endpoints and identifies the merchant for billing
This design simplifies integration since you only need to manage one token per upload session.

​
Best Practices

For the best user experience, call the processing endpoint as soon as the TUS upload completes. The delegation token has a 5-minute expiration, so don’t delay processing.
Since the data is returned directly, you can display results to your users immediately without waiting for webhooks or polling.
Call /v1/routes/from-upload to dynamically discover available processing endpoints and their capabilities, rather than hardcoding endpoint paths.
Each endpoint specifies which file types it can process. Use the accepted_file_types field from route discovery to validate files before upload.

​
Complete Integration Example

// 1. Get delegation token
const tokenResponse = await fetch('https://api.superseeded.ai/v1/auth/delegate-upload', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    merchant_id: 'merchant_123'
  })
});
const { delegation_token } = await tokenResponse.json();

// 2. Upload file via TUS
const upload = new tus.Upload(file, {
  endpoint: 'https://secure.superseeded.ai/files/',
  headers: {
    'Authorization': `Bearer ${delegation_token}`
  },
  onSuccess: async () => {
    const fileUrl = upload.url;

    // 3. Process uploaded file
    const processResponse = await fetch('https://api.superseeded.ai/v1/verify/plant-names', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${delegation_token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        file_url: fileUrl,
        filename: file.name
      })
    });

    const results = await processResponse.json();

    // 4. Display results to user
    displayResults(results);
  }
});

upload.start();