Skip to main content

API Reference

Zingle exposes a RESTful API built on FastAPI. All endpoints are prefixed with /api/v1 and require authentication via JWT bearer tokens.

Authentication​

MethodEndpointDescription
POST/api/v1/auth/signupCreate a new user account
POST/api/v1/auth/loginAuthenticate and receive JWT tokens
POST/api/v1/auth/refreshRefresh an expired access token
POST/api/v1/auth/logoutInvalidate the current session
GET/api/v1/auth/meGet the authenticated user's profile
GET/api/v1/auth/tokenGet current token details

GitHub OAuth​

MethodEndpointDescription
GET/api/v1/auth/github/authorize-urlGet the GitHub OAuth authorization URL
POST/api/v1/auth/github/callbackExchange GitHub OAuth code for access token

Repositories​

MethodEndpointDescription
GET/api/v1/repositoriesList all connected repositories
GET/api/v1/repositories/availableList available repositories for connection
GET/api/v1/repositories/branchesList branches for a repository
POST/api/v1/repositories/connectConnect a new repository
GET/api/v1/repositories/sync-statusGet sync status for a repository
POST/api/v1/repositories/syncTrigger a repository re-sync
DELETE/api/v1/repositories/{id}Disconnect a repository

Connections​

Snowflake​

MethodEndpointDescription
GET/api/v1/connections/snowflakeGet current Snowflake connection details
POST/api/v1/connections/snowflakeCreate or update Snowflake connection
DELETE/api/v1/connections/snowflakeDisconnect Snowflake

Airflow​

MethodEndpointDescription
GET/api/v1/connections/airflowGet current Airflow connection details
POST/api/v1/connections/airflowCreate or update Airflow connection
DELETE/api/v1/connections/airflowDisconnect Airflow

Data Pipelines (Models)​

MethodEndpointDescription
POST/api/v1/models/create-prCreate a GitHub PR for model changes

Request body​

{
  "repo_id": "string",
  "model_name": "string",
  "sql_content": "string",
  "yaml_content": "string",
  "test_content": "string"
}

The endpoint validates the repository belongs to the current workspace and retrieves the stored GitHub access token before creating the PR.

Semantic Layer​

MethodEndpointDescription
POST/api/v1/semantic-layer/create-prCreate a GitHub PR for semantic layer changes

Creates or updates YAML semantic definitions in the connected repository.

Compute Engine​

MethodEndpointDescription
POST/api/v1/compute-engine/pipelines/{pipeline_id}/create-prCreate a PR for compute optimization

Applies a compute engine change suggestion to a specific pipeline via pull request.

Data Model Optimization​

MethodEndpointDescription
POST/api/v1/manage-model/merge/{opportunity_id}/create-prCreate a PR for model merge optimization

Consolidates duplicate model logic into a single model via pull request.

Workspace Settings​

MethodEndpointDescription
GET/api/v1/settingsRetrieve current workspace settings
PUT/api/v1/settingsUpdate workspace settings (supports partial updates)

Error responses​

All error responses follow a consistent format:

{
  "detail": {
    "error_code": "SNOWFLAKE_AUTH_FAILED",
    "message": "Authentication failed for the provided credentials"
  }
}

Common error codes​

CodeDescription
ACCESS_TOKEN_REQUIREDGitHub access token not found on the connection
REPO_NOT_FOUNDRepository doesn't belong to the workspace
SNOWFLAKE_AUTH_FAILEDSnowflake credential validation failed
SNOWFLAKE_INVALID_ACCOUNTSnowflake account identifier is incorrect
SNOWFLAKE_RESOURCE_NOT_FOUNDWarehouse, database, or schema not found
SNOWFLAKE_CONNECTION_TIMEOUTConnection to Snowflake timed out (30s limit)
AIRFLOW_TIMEOUTAirflow API did not respond in time
AIRFLOW_CONNECTION_FAILEDCould not reach the Airflow instance