Get Semantic Model

Get the workspace semantic model as agentserve.model.yaml holds it: the published model, or with source=draft the caller’s own draft. Drafts, versions and diffs are available while model drafts are turned on for the deployment; otherwise these operations answer 404. Workspace API keys return 403; use a personal API key or scoped OAuth token.

OAuth scope: api:read.

GET/api/v2/semantic-model

Authorization

X-API-Key<token>

Your Agent Serve API key, personal or workspace-scoped. Generate one under Settings, then API Keys. Operations that reject workspace keys say so in their own description.

In: header

Query Parameters

workspaceId*string

Unique workspace identifier.

Length1 <= length <= 128
source?string

Which model: the published one, or the caller’s own draft.

Default"published"
Value in"published" | "draft"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://agentserve.valnoraelric.com/api/v2/semantic-model?workspaceId=string" \  -H "X-API-Key: YOUR_API_KEY"
{
  "data": {
    "workspaceId": "workspace-123",
    "source": "published",
    "draftId": null,
    "version": 4,
    "updatedAt": "2026-10-30T09:00:00.000Z",
    "model": {
      "entities": [
        {
          "id": "e_orders",
          "name": "Orders",
          "tableId": "tbl_orders",
          "synonyms": [
            "sales"
          ],
          "attributes": [
            {
              "name": "Region",
              "column": "region",
              "role": "dimension"
            }
          ],
          "measures": [
            {
              "name": "Revenue",
              "column": "amount",
              "aggregate": "sum"
            }
          ],
          "relationships": []
        }
      ]
    }
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request"
  }
}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}
{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient workspace permissions",
    "details": {
      "code": "INSUFFICIENT_WORKSPACE_ROLE"
    }
  }
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Not found"
  }
}
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "API rate limit exceeded",
    "details": {
      "retryAfter": "2026-01-01T00:00:30.000Z"
    }
  }
}
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  }
}
{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable"
  }
}
POSTDiff Semantic ModelPUTPush Semantic Model Draft