Developer

REST API Reference

Integrate Seismic Swift AI into your workflows with our comprehensive REST API. Every endpoint is authenticated, rate-limited, and audited.

Overview

Every platform capability is available programmatically. The dashboard is itself a consumer of the same endpoints you will use. All endpoints return consistent JSON envelopes, use ISO 8601 timestamps, and provide RFC 7807 Problem Details on errors.

The API is specified as OpenAPI 3.1 and served at /v1/openapi.json. Interactive documentation is available at /docs. Rate limit headers are present on every response — including 2xx responses.

Authentication

Azure AD OIDC — JWT RS256

Every request must carry a valid bearer token. Tokens are validated on every request — there is no token caching in the API tier.

Method	Value	Detail
Protocol	Azure AD OIDC + JWT RS256	Bearer tokens signed with RSA-256. Public keys served via JWKS endpoint for client-side verification.
API Keys	Service account keys	Long-lived API keys for service accounts with instant revocation. Keys are hashed at rest (SHA-256 / FIPS 180-4) — the plaintext is never stored.
Scopes	OAuth 2.0 fine-grained	Scopes: jobs:read, jobs:write, surveys:read, surveys:write, exports:read, governance:admin. Principle of least privilege enforced at the route level.
Isolation	JWT tid claim	Every request carries the tenant ID in the JWT tid claim. Server validates NFC normalization, homoglyph detection, and control character rejection before routing.

Rate Limiting

Per-tenant sliding window

Atomic sliding window rate limiting with burst protection prevents thundering-herd spikes. Token bucket burst control keeps capacity balanced. Cross-tenant fairness enforcement across all tenants.

Tier	Limit	Burst	Cost Model	Notes
Standard	Tier-based limits	Burst-protected	Unit cost per endpoint	Default for Geoscientist role.
Professional	Higher throughput	Burst-protected	Cost-based per endpoint	Admin role and above.
Enterprise	Custom	Custom	Negotiated	Dedicated cache partition. Contact sales.

Key Endpoints

Core API surface

Method	Endpoint	Scope	Description
POST	`/api/v1/jobs`	`jobs:write`	Create a pipeline job. Accepts survey_id, pipeline stages, and processing parameters. Returns HTTP 202 with job_id and estimated_duration_s.
GET	`/api/v1/jobs/{id}`	`jobs:read`	Get job status. Returns state machine position (PENDING → RUNNING → REVIEW → APPROVED → EXPORTING → COMPLETE), progress percentage, and stage timings.
GET	`/api/v1/jobs/{id}/results`	`jobs:read`	Download pipeline results. Returns signed Azure Blob Storage URL valid for 1 hour. Includes SHA-256 checksum header for integrity verification.
POST	`/api/v1/upload`	`surveys:write`	Upload SEG-Y, LAS, or GeoTIFF. Streaming upload with X-Content-SHA256 integrity header. Returns survey_id on success. Max 50 GB per file.
GET	`/api/v1/exports/{id}`	`exports:read`	Download a completed export. Returns format metadata, SHA-256 hash, OSDU record ID, and a signed download URL.
GET	`/api/v1/governance/tenants`	`governance:admin`	List all tenants. Cursor-based pagination. Returns id, name, tier, status, quota utilisation, and cascade health.
POST	`/api/v1/governance/users`	`governance:admin`	Create a user. Assigns role (Viewer / Geoscientist / Admin / SuperAdmin). Triggers RBAC validation with privilege escalation prevention.

Code Examples

Create a job in under a minute

The API returns immediately with a job ID. Poll GET /api/v1/jobs/{id} or subscribe to the job.completed webhook for progress.

cURL

curl -X POST https://api.seismicswiftai.com/api/v1/jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "survey_id": "survey-2024-north-sea-001",
    "pipeline": ["denoise", "autotrack", "detect"],
    "parameters": {
      "denoise_method": "unet_3d",
      "quality_gates": true,
      "export_formats": ["segy", "las"]
    }
  }'

Returns HTTP 202 Accepted with job_id and estimated_duration_s.

Python (httpx)

import httpx

async def create_job(token: str, survey_id: str) -> dict:
    async with httpx.AsyncClient(
        base_url="https://api.seismicswiftai.com",
        headers={"Authorization": f"Bearer {token}"},
        timeout=30.0,
    ) as client:
        response = await client.post(
            "/api/v1/jobs",
            json={
                "survey_id": survey_id,
                "pipeline": ["denoise", "autotrack", "detect"],
                "parameters": {
                    "denoise_method": "unet_3d",
                    "quality_gates": True,
                },
            },
        )
        response.raise_for_status()
        return response.json()  # {"job_id": "...", "estimated_duration_s": 120}

Requires pip install httpx. Full async — compatible with FastAPI and asyncio.

Response Headers

Standard headers on every response

Every API response includes rate limit, tracing, and tenant headers. Use these to build observability into your integration and handle throttling gracefully.

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window for this tenant and tier.
`X-RateLimit-Remaining`	Requests remaining in the current window.
`X-RateLimit-Reset`	Unix timestamp at which the rate limit window resets.
`X-Request-ID`	Unique request identifier for distributed tracing. Correlates with OpenTelemetry spans (W3C TraceContext).

SDKs

Native language support

Official SDKs generated from the OpenAPI 3.1 specification for type safety and accuracy.

Python SDK

pip install seismicswift

Available

Full async support via httpx. Type-annotated models generated from OpenAPI 3.1 schema. Compatible with Python 3.10+.

TypeScript SDK

npm install @seismicswift/sdk

Coming Soon

Full type safety with Zod validation. Works in Node.js and browser environments. ESM + CJS dual bundle. Target: Q3 2026.

Developer

Start building

Browse the interactive API documentation or schedule a demo to request API credentials and a sandbox environment.

Start Building Schedule Demo