Granica APIs V1

REST API reference for the Granica platform — tables, schedules, crunch, vacuum, catalog connections, Optimus, object maintenance, and more.

Overview

The Granica REST API (v1) lets you programmatically manage all aspects of the Granica platform, including table onboarding, compaction scheduling, catalog connections, query optimization, and object maintenance.

Base path: /api/v1

All requests require valid authentication credentials. Responses use standard HTTP status codes; 422 indicates a validation error with detail in the response body.

Health

Health Check

GET /api/v1/health

Health check endpoint. Returns 200 when the API is operational.

Configuration

Get Config

GET /api/v1/config

Get customer configuration.

Response	Description
`200`	Returns the current customer configuration.

Update Config

PUT /api/v1/config

Update customer configuration.

Request body: CustomerConfigUpdate

Response	Description
`200`	Returns the updated configuration.
`422`	Validation error.

Tables

List Tables

GET /api/v1/tables

List all tables with their schedules. Supports filtering by status and name. Use name to resolve a table's ID by its unique name (e.g. after a 409 on POST /tables).

Parameter	In	Required	Description
`offset`	query	No	Pagination offset. Default: `0`.
`limit`	query	No	Results per page. Default: `100`.
`status`	query	No	Filter by onboarding status (e.g. `pending`, `active`, `failed`).
`name`	query	No	Filter by exact table name.

Create Table

POST /api/v1/tables

Register a table for onboarding. Schedule is added separately after onboarding completes. Partition pattern, date filter, cluster and enumerated columns are auto-discovered during onboarding.

Request body: TableCreate

{
  "name": "orders",
  "uri": "s3://bucket/data/orders",
  "format": "delta",
  "priority": "P2"
}

Response	Description
`201`	Table created successfully.
`422`	Validation error.

Get Table

GET /api/v1/tables/{table_id}

Get a table by ID, including its schedule.

Update Table

PUT /api/v1/tables/{table_id}

Update table configuration.

Request body: TableUpdate

{
  "priority": "P1",
  "target_file_size_mb": 512
}

Delete Table

DELETE /api/v1/tables/{table_id}

Delete a table and its schedules. Returns 204 on success.

Get Inventory History

GET /api/v1/tables/{table_id}/inventory-history

Append-only audit of inventory_report_uri changes for a table, ordered newest-first. Rows are retained after the table is deleted, so this may return audit history for removed tables.

Parameter	In	Required	Description
`offset`	query	No	Pagination offset. Default: `0`.
`limit`	query	No	Results per page. Default: `50`.

Schedules

Create Schedule

POST /api/v1/tables/{table_id}/schedule

Create a schedule for a table. Only works when onboarding_status is active.

Request body: ScheduleCreate

Daily with lookback range (T-15 to T-2):

{
  "schedule_type": "daily",
  "lookback_start": 15,
  "lookback_end": 2,
  "run_time_utc": "02:00"
}

Backfill:

{
  "schedule_type": "backfill",
  "backfill_col": "event_date",
  "backfill_start_date": "2025-01-01",
  "backfill_end_date": "2025-12-31"
}

Get Schedule

GET /api/v1/tables/{table_id}/schedule

Get the schedule for a table.

Parameter	In	Required	Description
`job_type`	query	No	Filter by job type: `crunch`, `vacuum`, or `partition_expiration`.

Update Schedule

PUT /api/v1/tables/{table_id}/schedule

Update the schedule for a table.

Request body: ScheduleUpdate

{
  "lookback_start": 7,
  "lookback_end": 1,
  "run_time_utc": "03:00",
  "enabled": false
}

Delete Schedule

DELETE /api/v1/tables/{table_id}/schedule

Delete the schedule for a table. Returns 204 on success.

Parameter	In	Required	Description
`job_type`	query	No	Filter by job type.

Onboarding

Get Onboarding Status

GET /api/v1/onboarding/{table_id}/status

Get the onboarding status for a table.

Retry Onboarding

POST /api/v1/onboarding/{table_id}/retry

Retry onboarding for a failed table. Only tables with onboarding_status='failed' can be retried. Resets status to retry for the onboarding scheduler to pick up.

Slots

Get Slot Info

GET /api/v1/slots/{run_time_utc}

Get slot capacity information for a specific time. Time format: HH:MM (e.g. 02:30, 14:00).

Crunch

Trigger Crunch

POST /api/v1/tables/{table_id}/crunch

Directly trigger a crunch job, bypassing the schedule.

Request body: CrunchTrigger

Two modes (mutually exclusive):

Lookback mode (relative to today):

{
  "lookback_start": 15,
  "lookback_end": 2,
  "priority": "P2"
}

Backfill mode (absolute dates):

{
  "backfill_start_date": "2026-01-01",
  "backfill_end_date": "2026-01-15",
  "priority": "P2",
  "cluster_columns": "user_id,event_type"
}

Parameter	In	Required	Description
`skip_recipe_check`	query	No	Skip recipe completion check (for testing). Default: `false`.

List Table Crunch Jobs

GET /api/v1/tables/{table_id}/crunch

List crunch jobs for a specific table.

Parameter	In	Required	Description
`offset`	query	No	Pagination offset. Default: `0`.
`limit`	query	No	Results per page. Default: `100`.
`status`	query	No	Filter by crunch job status.
`job_type`	query	No	Filter by job type: `crunch` or `optimize`.

List All Crunch Jobs

GET /api/v1/crunch

List all crunch jobs with optional filters.

Parameter	In	Required	Description
`offset`	query	No	Default: `0`.
`limit`	query	No	Default: `100`.
`table_id`	query	No	Filter by table.
`status`	query	No	Filter by crunch job status.
`job_type`	query	No	Filter by job type.

Get Crunch Job With Metrics

GET /api/v1/crunch/{crunch_id}/metrics

Get a crunch job with aggregated metrics including DRR (Data Reduction Rate), bytes before/after, and optimization metrics.

Cancel Crunch Job

POST /api/v1/crunch/{crunch_id}/cancel

Cancel a scheduled or in-flight crunch job.

Vacuum

Trigger Vacuum

POST /api/v1/tables/{table_id}/vacuum

Trigger a vacuum operation on a Delta or Iceberg table.

Request body: VacuumTrigger

List Table Vacuum Jobs

GET /api/v1/tables/{table_id}/vacuum

List vacuum jobs for a table.

Parameter	In	Required	Description
`offset`	query	No	Default: `0`.
`limit`	query	No	Default: `100`.
`status`	query	No	Filter by status.

Trigger Hard Delete

POST /api/v1/vacuum/hard-delete

Hard-delete files for all expired PENDING_DELETE records on demand.

Parameter	In	Required	Description
`dry_run`	query	No	Preview without deleting. Default: `false`.
`table_id`	query	No	Scope to a specific table.
`limit`	query	No	Max records per call. Default: `500`, cap `5000`.

Partition Expiration

Trigger Partition Expiration

POST /api/v1/tables/{table_id}/partition-expiration

Trigger partition expiration (DELETE-only) on a Delta table. Files are tombstoned in the table log; physical reclamation is handled by the vacuum pipeline.

Request body: PartitionExpirationTrigger

List Partition Expiration Jobs

GET /api/v1/tables/{table_id}/partition-expiration

List partition expiration jobs for a table.

Parameter	In	Required	Description
`offset`	query	No	Default: `0`.
`limit`	query	No	Default: `100`.
`status`	query	No	Filter by status.

Validate Partition Expiration Policy

POST /api/v1/tables/{table_id}/partition-expiration/validate

Preflight a partition expiration policy before persisting. Side-effect-free — no DB writes.

Request body: PartitionExpirationValidateRequest

Pending Deletions

List Pending Deletions

GET /api/v1/pending-deletions

List pending deletions with optional filters.

Parameter	In	Required	Description
`offset`	query	No	Default: `0`.
`limit`	query	No	Default: `20`.
`status`	query	No	Filter by status.
`table_id`	query	No	Filter by table.
`action_type`	query	No	Filter by action type.
`vacuum_mode`	query	No	Filter by vacuum mode.

Get Pending Deletion Stats

GET /api/v1/pending-deletions/stats

Aggregated pending deletion counts by status.

Parameter	In	Required	Description
`table_id`	query	No	Scope to a specific table.

Get Pending Deletion

GET /api/v1/pending-deletions/{deletion_id}

Get a single pending deletion record.

Recover Pending Deletion

POST /api/v1/pending-deletions/{deletion_id}/recover

Recover a pending deletion to prevent hard-delete. Only PENDING_DELETE records can be recovered.

Request body: RecoverRequest

Catalog Connections

Test Connection

POST /api/v1/catalog-connections/test

Test a catalog connection without persisting. Validates credentials by listing catalogs.

Request body: ConnectionTest

Create Connection

POST /api/v1/catalog-connections

Create a new catalog connection.

Request body: ConnectionCreate

List Connections

GET /api/v1/catalog-connections

List catalog connections.

Parameter	In	Required	Description
`offset`	query	No	Default: `0`.
`limit`	query	No	Default: `100`.
`is_active`	query	No	Filter by active status.

Get Connection

GET /api/v1/catalog-connections/{connection_id}

Get a single catalog connection.

Update Connection

PUT /api/v1/catalog-connections/{connection_id}

Update a catalog connection (partial update).

Request body: ConnectionUpdate

Delete Connection

DELETE /api/v1/catalog-connections/{connection_id}

Delete a catalog connection and all its synced metadata.

Parameter	In	Required	Description
`confirm`	query	No	Must be `true` to proceed. Deletion is irreversible.

Trigger Sync

POST /api/v1/catalog-connections/{connection_id}/sync

Trigger a catalog metadata sync. Runs in the background.

Parameter	In	Required	Description
`catalog`	query	No	Limit sync to a specific catalog.
`mode`	query	No	`full` (walk all tables, detect deletions) or `incremental` (Unity Catalog only). Default: `full`.

List Catalogs

GET /api/v1/catalog-connections/{connection_id}/catalogs

List catalogs for a connection.

List Schemas

GET /api/v1/catalog-connections/{connection_id}/catalogs/{catalog_name}/schemas

List schemas within a catalog.

List Tables (Catalog)

GET /api/v1/catalog-connections/{connection_id}/tables

List tables with filtering, sorting, and pagination.

Parameter	In	Required	Description
`catalog`	query	No	Filter by catalog.
`schema`	query	No	Filter by schema.
`prefix`	query	No	Table name prefix filter.
`search`	query	No	Search in full table name.
`format`	query	No	Filter by table format.
`table_type`	query	No	Filter by table type.
`min_size_bytes`	query	No	Minimum table size filter.
`max_size_bytes`	query	No	Maximum table size filter.
`has_partitions`	query	No	Filter by partitioning.
`sort_by`	query	No	Sort field. Default: `full_name`.
`sort_order`	query	No	`asc` or `desc`. Default: `asc`.
`offset`	query	No	Default: `0`.
`limit`	query	No	Default: `100`.

Get Table Detail (Catalog)

GET /api/v1/catalog-connections/{connection_id}/tables/{full_name}

Get full table detail including JSONB fields.

Feature Flags

Get Feature Flag

GET /api/v1/feature-flags/{key}

Return the enabled state of a single feature flag. Returns {"key": key, "enabled": false} when the flag is missing — treat absence as disabled.

Optimus (Query Optimization)

Create Optimus Run

POST /api/v1/optimus/runs

Create and trigger an Optimus recommendation run.

Request body: OptimusRunCreate

Retry Optimus Run

POST /api/v1/optimus/runs/{submission_id}/retry

Retry a failed Optimus submission. Returns 422 unless the effective status is failed.

Sync Optimus Submission Now

POST /api/v1/optimus/runs/{submission_id}/sync-now

Fire an out-of-cycle Optimus run immediately, regardless of the configured daily_sync_time_utc.

Delete Optimus Submission

DELETE /api/v1/optimus/runs/{submission_id}

Hard-delete a submission. Cascades to runs, recommendations, and per-day predicate combos.

Get Optimus Run

GET /api/v1/optimus/runs/{run_id}

Get Optimus submission dispatch metadata and latest-run summary.

Update Optimus Submission

PATCH /api/v1/optimus/runs/{run_id}

Partially update an Optimus submission. Use to update name, lookback_days, daily_sync_time_utc, query_logs_uri, or active (pause/resume toggle).

Request body: OptimusSubmissionUpdate

List Optimus Recommendations

GET /api/v1/optimus/runs/{run_id}/recommendations

List per-table recommendations for the submission's latest run.

Parameter	In	Required	Description
`offset`	query	No	Default: `0`.
`limit`	query	No	Default: `100`.

Apply Optimus Recommendation

POST /api/v1/optimus/recommendations/{recommendation_id}/apply

Apply one persisted Optimus recommendation to a managed table policy.

Request body: OptimusRecommendationApplyRequest

List Optimus Tables With Recommendations

GET /api/v1/optimus/runs/{run_id}/tables

List tables that have at least one recommendation under this submission.

Get Optimus Table Metrics

GET /api/v1/optimus/runs/{run_id}/tables/{table_fqn}/metrics

Per-day metric series for a table over the last days days, with applied-recommendation markers.

Parameter	In	Required	Description
`days`	query	No	Window width in days (inclusive of today). Default: `90`.

Object Maintenance

Create Location

POST /api/v1/object-maintenance/locations

Request body: LocationCreate

List Locations

GET /api/v1/object-maintenance/locations

List object maintenance locations.

Get Location

GET /api/v1/object-maintenance/locations/{location_id}

Get a single object maintenance location.

Update Location

PATCH /api/v1/object-maintenance/locations/{location_id}

Partial update of an object maintenance location.

Request body: LocationUpdate

Parameter	In	Required	Description
`location_id`	query	No	Filter to a single location.
`management_state`	query	No	Filter: `unmanaged`, `active`, `paused`, or `error`.
`source_state`	query	No	Filter: `present` or `missing`.

Get Prefix

GET /api/v1/object-maintenance/prefixes/{prefix_id}

Get a single managed prefix with parent-location summary and policy details.

Enable Maintenance

POST /api/v1/object-maintenance/locations/{location_id}/prefixes/{prefix_id}/enable

Enable maintenance on a prefix (unmanaged → active). Idempotent on already-active prefixes.

Response	Description
`200`	Already enabled — no-op.
`201`	Newly enabled.
`404`	Prefix or location not found.
`422`	Invalid lifecycle transition.

Get Prefix Policy

GET /api/v1/object-maintenance/prefixes/{prefix_id}/policy

Return the active policy and active version for a prefix.

Upsert Prefix Policy

PUT /api/v1/object-maintenance/prefixes/{prefix_id}/policy

Create or replace the active policy. Appends a new version and deactivates the prior one atomically. Auto-activates the prefix if still unmanaged.

Request body: PolicyUpsert

Request body: ActionRequest

Endpoint	Description
`GET /api/v1/object-maintenance/locations/{location_id}/discovery/schedules`	List discovery-attempt history for a location.
`GET /api/v1/object-maintenance/discovery/schedules/{schedule_id}`	Full detail for a discovery attempt.
`GET /api/v1/object-maintenance/discovery/schedules/{schedule_id}/state`	Live progress snapshot (console polls at 5s cadence while running).
`GET /api/v1/object-maintenance/discovery/schedules/{schedule_id}/plan`	Plan summary — bins, total bytes, estimated wall-time.
`POST /api/v1/object-maintenance/discovery/schedules/{schedule_id}/pause`	Pause a running discovery.
`POST /api/v1/object-maintenance/discovery/schedules/{schedule_id}/resume`	Resume a paused discovery.
`POST /api/v1/object-maintenance/discovery/schedules/{schedule_id}/restart`	Restart a discovery from scratch (cancels prior run, clears state).
`POST /api/v1/object-maintenance/discovery/schedules/{schedule_id}/complete`	Mark a discovery completed (dragon driver terminal callback).
`POST /api/v1/object-maintenance/discovery/schedules/{schedule_id}/skip-bin/{bin_id}`	Skip a single wedged bin without restarting the full discovery.
`GET /api/v1/object-maintenance/discovery/schedules/{schedule_id}/effective-config`	Three-layer config resolution for a schedule's parent location.

On this page