---
title: "Spec"
description: "The `Spec` entity."
section: "Reference"
group: "Types"
order: 205
---

## Definition

```ts
interface Spec {
  id: string;
  workspaceId: string;
  name: string;
  description: string | null;
  sourceUrl: string;
  specFormat: "openapi-3.0" | "openapi-3.1" | "swagger-2.0";
  currentVersionId: string | null;
  baseUrl: string | null;
  authHeaderName: string | null;
  authValuePrefix: string | null;
  authSecretId: string | null;
  solutionId: string | null;
  createdBy: string;
  deletedAt: string | null;
  retentionTier: "short" | "medium" | "long" | "none" | null;
  createdAt: string;
  updatedAt: string;
}
```

## Fields

| Field              | Type                                              | Notes                                                                                                                                                                                                                          |
| ------------------ | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`               | `string`                                          | `readonly` `required`                                                                                                                                                                                                          |
| `workspaceId`      | `string`                                          | `required` — Workspace that owns this spec.                                                                                                                                                                                    |
| `name`             | `string`                                          | `required` — Human-readable name for the spec.                                                                                                                                                                                 |
| `description`      | `string \| null`                                  | `required` — Optional longer-form description.                                                                                                                                                                                 |
| `sourceUrl`        | `string`                                          | `required` — URL the spec is fetched from. Re-fetched on manual refresh; scheduled refresh deferred to v1.1.                                                                                                                   |
| `specFormat`       | `"openapi-3.0" \| "openapi-3.1" \| "swagger-2.0"` | `required`                                                                                                                                                                                                                     |
| `currentVersionId` | `string \| null`                                  | `required` — Latest spec_version row holding the most recently fetched spec. Null until the first successful ingest.                                                                                                           |
| `baseUrl`          | `string \| null`                                  | `required` — Override for the spec's `servers[]` base URL. Useful when the spec documents a production URL but the workspace wants to hit staging. Null = use spec.servers[0].                                                 |
| `authHeaderName`   | `string \| null`                                  | `required` — v1 API-key auth: HTTP header to set when calling upstream operations (e.g. `Authorization`, `X-Api-Key`). Null = no auth.                                                                                         |
| `authValuePrefix`  | `string \| null`                                  | `required` — Prefix prepended to the secret value when building the header (e.g. `Bearer `). Null = raw value with no prefix.                                                                                                  |
| `authSecretId`     | `string \| null`                                  | `required` — Reference to the workspace secret holding the API key value. Null = no auth.                                                                                                                                      |
| `solutionId`       | `string \| null`                                  | `required` — Optional Solution that wraps the entities generated from this spec. Can be auto-created at import time or an existing solution the user picks. Null = generated entities live in the workspace catalog unwrapped. |
| `createdBy`        | `string`                                          | `required` — User who created the spec.                                                                                                                                                                                        |
| `deletedAt`        | `string \| null`                                  | `required` — ISO-8601 timestamp of soft-delete; null while active. Cleanup worker hard-deletes once `deletedAt + retentionTier.days` passes.                                                                                   |
| `retentionTier`    | `"short" \| "medium" \| "long" \| "none" \| null` | `required` — Retention tier snapshotted at delete time.                                                                                                                                                                        |
| `createdAt`        | `string`                                          | `readonly` `required`                                                                                                                                                                                                          |
| `updatedAt`        | `string`                                          | `readonly` `required`                                                                                                                                                                                                          |