POST /scan

ImplementadoSin versión del tren todavía· generada desde apps/docs/generated/openapi/catalog-svc.json

track/docs track/domain-media dec-0116 dec-0118 dec-0124track/docs:DC2

Página generada desde apps/catalog-svc/src/app.aot.ts. No se edita a mano: bun run docs:gen la regenera y bun run docs:check falla si difiere.

POST /scan

Pide los facts del fichero al motor de medios del daemon (qry.media.probe sobre una raíz de STYX_MEDIA_ROOTS, nunca una ruta absoluta), crea o actualiza el asset y su MediaIndex y publica evt.catalog.assetIndexed. Un fichero que el motor dice que no es un medio entra como asset unidentified (indexed=false, sin índice) en vez de rechazarse. Gasta un presupuesto propio por actor (5/s, ráfaga 20) además del del servicio.

Acceso: Bearer de identity con policy resource:asset:scan.

Campo	Valor
Servicio	`catalog-svc`
operationId	`postScan`
Policy (`dec-0118` §3)	`resource:asset:scan`
Tags	`catalog`

Cuerpo

Requerido: sí.

`application/json`

{
  "type": "object",
  "required": [
    "path"
  ],
  "properties": {
    "path": {
      "type": "string",
      "minLength": 1
    },
    "workId": {
      "type": "string"
    },
    "editionId": {
      "type": "string"
    }
  }
}

Respuestas

200

Asset creado o actualizado y, si el motor de medios del daemon lo reconoció, su MediaIndex. Sin índice (indexed: false) el asset queda unidentified.

application/json

{
  "type": "object",
  "required": [
    "asset",
    "indexed"
  ],
  "properties": {
    "asset": {
      "type": "object",
      "required": [
        "id",
        "editionId",
        "path",
        "sizeBytes",
        "kind",
        "createdAt",
        "updatedAt"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "editionId": {
          "type": "string"
        },
        "path": {
          "type": "string"
        },
        "sizeBytes": {
          "type": "integer"
        },
        "fastHash": {
          "type": "string"
        },
        "container": {
          "type": "string"
        },
        "layout": {
          "type": "string",
          "enum": [
            "file",
            "tree",
            "image"
          ]
        },
        "identification": {
          "type": "string",
          "enum": [
            "identified",
            "unidentified"
          ]
        },
        "kind": {
          "type": "string",
          "const": "logical-composition"
        },
        "createdAt": {
          "type": "number"
        },
        "updatedAt": {
          "type": "number"
        }
      }
    },
    "index": {
      "type": "object",
      "required": [
        "id",
        "assetId",
        "indexVersion",
        "container",
        "durationMs",
        "bitrateBps",
        "streams",
        "capabilities",
        "createdAt"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "assetId": {
          "type": "string"
        },
        "indexVersion": {
          "type": "integer"
        },
        "container": {
          "type": "string"
        },
        "durationMs": {
          "type": "integer",
          "minimum": 0,
          "maximum": 2147483647
        },
        "bitrateBps": {
          "type": "integer",
          "minimum": 0,
          "maximum": 2147483647
        },
        "streams": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "index",
              "type",
              "codec",
              "defaultFlag"
            ],
            "properties": {
              "index": {
                "type": "integer"
              },
              "type": {
                "type": "string",
                "enum": [
                  "video",
                  "audio",
                  "subtitle",
                  "attachment",
                  "data"
                ]
              },
              "codec": {
                "type": "string"
              },
              "language": {
                "type": "string"
              },
              "defaultFlag": {
                "type": "boolean"
              },
              "bitRateBps": {
                "type": "integer"
              },
              "width": {
                "type": "integer"
              },
              "height": {
                "type": "integer"
              },
              "frameRate": {
                "type": "number"
              },
              "channels": {
                "type": "integer"
              },
              "sampleRate": {
                "type": "integer"
              }
            }
          }
        },
        "capabilities": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "keyframesMs": {
          "type": "array",
          "items": {
            "type": "number"
          }
        },
        "createdAt": {
          "type": "number"
        }
      }
    },
    "indexed": {
      "type": "boolean"
    }
  },
  "description": "Asset creado o actualizado y, si el motor de medios del daemon lo reconoció, su MediaIndex. Sin índice (`indexed: false`) el asset queda `unidentified`."
}

400

Problem Details (RFC 9457), status 400. Códigos: parse, CATALOG_INVALID_PATH, CATALOG_PERMISSION_DENIED, CATALOG_MEDIA_UNSUPPORTED, CATALOG_MEDIA_TIMELINE_OUT_OF_RANGE, CATALOG_INVALID_INPUT.

application/problem+json

{
  "anyOf": [
    {
      "type": "object",
      "required": [
        "type",
        "title",
        "status",
        "code"
      ],
      "properties": {
        "type": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "status": {
          "type": "number",
          "const": 400
        },
        "code": {
          "type": "string",
          "const": "parse"
        },
        "detail": {
          "type": "string"
        }
      },
      "x-styx-media-type": "application/problem+json"
    },
    {
      "type": "object",
      "required": [
        "type",
        "title",
        "status",
        "code",
        "retryable",
        "category"
      ],
      "properties": {
        "type": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "status": {
          "type": "number",
          "const": 400
        },
        "code": {
          "type": "string",
          "enum": [
            "CATALOG_INVALID_PATH",
            "CATALOG_PERMISSION_DENIED",
            "CATALOG_MEDIA_UNSUPPORTED",
            "CATALOG_MEDIA_TIMELINE_OUT_OF_RANGE",
            "CATALOG_INVALID_INPUT"
          ]
        },
        "detail": {
          "type": "string"
        },
        "instance": {
          "type": "string"
        },
        "retryable": {
          "type": "boolean"
        },
        "category": {
          "type": "string",
          "enum": [
            "transient",
            "permanent",
            "recoverable"
          ]
        }
      },
      "x-styx-media-type": "application/problem+json"
    }
  ]
}

401

Problem Details (RFC 9457), status 401. Códigos: unauthenticated, reauth-required.

application/problem+json

{
  "type": "object",
  "required": [
    "type",
    "title",
    "status",
    "code"
  ],
  "properties": {
    "type": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "number",
      "const": 401
    },
    "code": {
      "type": "string",
      "enum": [
        "unauthenticated",
        "reauth-required"
      ]
    },
    "detail": {
      "type": "string"
    }
  },
  "x-styx-media-type": "application/problem+json"
}

403

Problem Details (RFC 9457), status 403. Códigos: forbidden.

application/problem+json

{
  "type": "object",
  "required": [
    "type",
    "title",
    "status",
    "code"
  ],
  "properties": {
    "type": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "number",
      "const": 403
    },
    "code": {
      "type": "string",
      "const": "forbidden"
    },
    "detail": {
      "type": "string"
    }
  },
  "x-styx-media-type": "application/problem+json"
}

404

Problem Details (RFC 9457), status 404. Códigos: CATALOG_ASSET_NOT_FOUND, CATALOG_WORK_NOT_FOUND, CATALOG_EDITION_NOT_FOUND.

application/problem+json

{
  "type": "object",
  "required": [
    "type",
    "title",
    "status",
    "code",
    "retryable",
    "category"
  ],
  "properties": {
    "type": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "number",
      "const": 404
    },
    "code": {
      "type": "string",
      "enum": [
        "CATALOG_ASSET_NOT_FOUND",
        "CATALOG_WORK_NOT_FOUND",
        "CATALOG_EDITION_NOT_FOUND"
      ]
    },
    "detail": {
      "type": "string"
    },
    "instance": {
      "type": "string"
    },
    "retryable": {
      "type": "boolean"
    },
    "category": {
      "type": "string",
      "enum": [
        "transient",
        "permanent",
        "recoverable"
      ]
    }
  },
  "x-styx-media-type": "application/problem+json"
}

422

Problem Details (RFC 9457), status 422. Códigos: validation.

application/problem+json

{
  "type": "object",
  "required": [
    "type",
    "title",
    "status",
    "code"
  ],
  "properties": {
    "type": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "number",
      "const": 422
    },
    "code": {
      "type": "string",
      "const": "validation"
    },
    "on": {
      "type": "string"
    },
    "property": {
      "type": "string"
    },
    "detail": {
      "type": "string"
    }
  },
  "x-styx-media-type": "application/problem+json"
}

429

Problem Details (RFC 9457), status 429. Códigos: rate-limited.

application/problem+json

{
  "type": "object",
  "required": [
    "type",
    "title",
    "status",
    "code"
  ],
  "properties": {
    "type": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "number",
      "const": 429
    },
    "code": {
      "type": "string",
      "const": "rate-limited"
    },
    "detail": {
      "type": "string"
    }
  },
  "x-styx-media-type": "application/problem+json"
}

500

Problem Details (RFC 9457), status 500. Códigos: CATALOG_INTERNAL.

application/problem+json

{
  "type": "object",
  "required": [
    "type",
    "title",
    "status",
    "code",
    "retryable",
    "category"
  ],
  "properties": {
    "type": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "number",
      "const": 500
    },
    "code": {
      "type": "string",
      "const": "CATALOG_INTERNAL"
    },
    "detail": {
      "type": "string"
    },
    "instance": {
      "type": "string"
    },
    "retryable": {
      "type": "boolean"
    },
    "category": {
      "type": "string",
      "enum": [
        "transient",
        "permanent",
        "recoverable"
      ]
    }
  },
  "x-styx-media-type": "application/problem+json"
}

502

Problem Details (RFC 9457), status 502. Códigos: CATALOG_PROBE_FAILED.

application/problem+json

{
  "type": "object",
  "required": [
    "type",
    "title",
    "status",
    "code",
    "retryable",
    "category"
  ],
  "properties": {
    "type": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "number",
      "const": 502
    },
    "code": {
      "type": "string",
      "const": "CATALOG_PROBE_FAILED"
    },
    "detail": {
      "type": "string"
    },
    "instance": {
      "type": "string"
    },
    "retryable": {
      "type": "boolean"
    },
    "category": {
      "type": "string",
      "enum": [
        "transient",
        "permanent",
        "recoverable"
      ]
    }
  },
  "x-styx-media-type": "application/problem+json"
}

503

Problem Details (RFC 9457), status 503. Códigos: CATALOG_DB_WRITE_FAILED, CATALOG_DB_READ_FAILED, CATALOG_NATS_PUBLISH_FAILED.

application/problem+json

{
  "type": "object",
  "required": [
    "type",
    "title",
    "status",
    "code",
    "retryable",
    "category"
  ],
  "properties": {
    "type": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "number",
      "const": 503
    },
    "code": {
      "type": "string",
      "enum": [
        "CATALOG_DB_WRITE_FAILED",
        "CATALOG_DB_READ_FAILED",
        "CATALOG_NATS_PUBLISH_FAILED"
      ]
    },
    "detail": {
      "type": "string"
    },
    "instance": {
      "type": "string"
    },
    "retryable": {
      "type": "boolean"
    },
    "category": {
      "type": "string",
      "enum": [
        "transient",
        "permanent",
        "recoverable"
      ]
    }
  },
  "x-styx-media-type": "application/problem+json"
}

504

Problem Details (RFC 9457), status 504. Códigos: CATALOG_PROBE_TIMEOUT.

application/problem+json

{
  "type": "object",
  "required": [
    "type",
    "title",
    "status",
    "code",
    "retryable",
    "category"
  ],
  "properties": {
    "type": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "number",
      "const": 504
    },
    "code": {
      "type": "string",
      "const": "CATALOG_PROBE_TIMEOUT"
    },
    "detail": {
      "type": "string"
    },
    "instance": {
      "type": "string"
    },
    "retryable": {
      "type": "boolean"
    },
    "category": {
      "type": "string",
      "enum": [
        "transient",
        "permanent",
        "recoverable"
      ]
    }
  },
  "x-styx-media-type": "application/problem+json"
}

CuerpoCopiar enlace

application/jsonCopiar enlace

RespuestasCopiar enlace

200Copiar enlace

400Copiar enlace

401Copiar enlace

403Copiar enlace

404Copiar enlace

422Copiar enlace

429Copiar enlace

500Copiar enlace

502Copiar enlace

503Copiar enlace

504Copiar enlace

En esta página

Cuerpo

`application/json`

Respuestas

200

400

401

403

404

422

429

500

502

503

504