API docs
Book a demo

Content Enrichment API / Tags

List tags

Page

POST /v2/project/content/listTags

Return the calling project's internal tags as a plain array under Data (not paginated). The request body is empty.

Example request

curl -X POST 'https://api.ygo.ai/v2/project/content/listTags' \
  -H "Authorization: Bearer $YGO_API_KEY" \
  -H "X-Project-ID: $YGO_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

Authorization

Authorization: Bearer <key>

Project-scoped API key

Headers

  • X-Project-ID string (uuid) required

    Project UUID. Required for all project-scoped endpoints.

    Example
    $YGO_PROJECT_ID

Request body

application/json object ListTagsRequest

No request body is required for listing tags. The project is taken from the X-Project-ID header / authorized scope.

Example request: No body required
{}

Responses

200 OK

Tags retrieved successfully.

Headers

  • X-Trace-ID string

    Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

    Example
    abc123def456ghi789

Body

application/json object ListTagsResponse

Response envelope wrapping the project's tags as a plain array (not paginated).

  • Data array of object ProjectTag required

    The project's internal tags.

    Each item

    A project-private internal tag.

    4 fields
    • ID string (uuid) required

      Unique tag UUID.

      Example
      0192fc01-1111-7abc-8def-aaaaaaaaaaaa
    • ProjectID string (uuid) required

      UUID of the project that owns the tag.

      Example
      0192fa00-0000-7abc-8def-000000000000
    • Name string required

      Tag display name.

      Example
      Summer Campaign
    • CreatedBy string required

      Audit identity of who created the tag: a user token records the user's email; a project (proj_) machine token records its project-scoped identity (e.g. 'project:<project-uuid>').

      Example
      editor@example.com
Example response: A project with two tags
{
  "Data": [
    {
      "ID": "0192fc01-1111-7abc-8def-aaaaaaaaaaaa",
      "ProjectID": "0192fa00-0000-7abc-8def-000000000000",
      "Name": "Summer Campaign",
      "CreatedBy": "editor@example.com"
    },
    {
      "ID": "0192fc02-2222-7abc-8def-bbbbbbbbbbbb",
      "ProjectID": "0192fa00-0000-7abc-8def-000000000000",
      "Name": "Beachfront",
      "CreatedBy": "project:0192fa00-0000-7abc-8def-000000000000"
    }
  ]
}
400 Bad Request

Bad Request - Validation error or invalid request body.

Headers

  • X-Trace-ID string

    Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

    Example
    abc123def456ghi789

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

    Error detail containing a machine-readable code and human-readable message.

    3 fields
    • Code string required

      Machine-readable error code for programmatic handling.

      Example
      FORBIDDEN
    • Message string required

      Human-readable error message.

      Example
      Project access required
    • Fields array of object FieldError

      Field-level validation errors. Only present for VALIDATION_ERROR responses.

      Each item

      A single field-level validation error.

      4 fields
      • Field string required

        Name of the field that failed validation.

        Example
        Name
      • Message string required

        Human-readable validation error message for this field.

        Example
        Name cannot be empty
      • Code string

        Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

        Values
        REQUIRED TOO_LONG TOO_SHORT OUT_OF_RANGE TOO_MANY INVALID_FORMAT NOT_ALLOWED CONFLICT INVALID_ENCODING INSECURE_SCHEME UNSAFE_CONTENT REQUIRED_WHEN_ENABLED
        Example
        TOO_LONG
      • Params map of string to any

        Machine-readable values the message is built from, such as limits or allowed values. Keys are PascalCase; which keys are present depends on Code. Optional.

        Example
        {
          "Max": 100
        }
Example response: Malformed request body
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Invalid request body"
  }
}
401 Unauthorized

Unauthorized - Invalid or missing API key.

Headers

  • X-Trace-ID string

    Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

    Example
    abc123def456ghi789

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

    Error detail containing a machine-readable code and human-readable message.

    3 fields
    • Code string required

      Machine-readable error code for programmatic handling.

      Example
      FORBIDDEN
    • Message string required

      Human-readable error message.

      Example
      Project access required
    • Fields array of object FieldError

      Field-level validation errors. Only present for VALIDATION_ERROR responses.

      Each item

      A single field-level validation error.

      4 fields
      • Field string required

        Name of the field that failed validation.

        Example
        Name
      • Message string required

        Human-readable validation error message for this field.

        Example
        Name cannot be empty
      • Code string

        Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

        Values
        REQUIRED TOO_LONG TOO_SHORT OUT_OF_RANGE TOO_MANY INVALID_FORMAT NOT_ALLOWED CONFLICT INVALID_ENCODING INSECURE_SCHEME UNSAFE_CONTENT REQUIRED_WHEN_ENABLED
        Example
        TOO_LONG
      • Params map of string to any

        Machine-readable values the message is built from, such as limits or allowed values. Keys are PascalCase; which keys are present depends on Code. Optional.

        Example
        {
          "Max": 100
        }
Example response: Invalid API key
{
  "Error": {
    "Code": "UNAUTHORIZED",
    "Message": "Invalid API key"
  }
}
403 Forbidden

Forbidden - Valid API key but insufficient permissions for this operation. Also returned with code INSUFFICIENT_SCOPE when the API key does not carry the content.catalog:read permission this endpoint requires.

Headers

  • X-Trace-ID string

    Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

    Example
    abc123def456ghi789

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

    Error detail containing a machine-readable code and human-readable message.

    3 fields
    • Code string required

      Machine-readable error code for programmatic handling.

      Example
      FORBIDDEN
    • Message string required

      Human-readable error message.

      Example
      Project access required
    • Fields array of object FieldError

      Field-level validation errors. Only present for VALIDATION_ERROR responses.

      Each item

      A single field-level validation error.

      4 fields
      • Field string required

        Name of the field that failed validation.

        Example
        Name
      • Message string required

        Human-readable validation error message for this field.

        Example
        Name cannot be empty
      • Code string

        Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

        Values
        REQUIRED TOO_LONG TOO_SHORT OUT_OF_RANGE TOO_MANY INVALID_FORMAT NOT_ALLOWED CONFLICT INVALID_ENCODING INSECURE_SCHEME UNSAFE_CONTENT REQUIRED_WHEN_ENABLED
        Example
        TOO_LONG
      • Params map of string to any

        Machine-readable values the message is built from, such as limits or allowed values. Keys are PascalCase; which keys are present depends on Code. Optional.

        Example
        {
          "Max": 100
        }
Example response: Missing required scope
{
  "Error": {
    "Code": "INSUFFICIENT_SCOPE",
    "Message": "token lacks scope content.catalog:read"
  }
}
Example response: Project access required
{
  "Error": {
    "Code": "FORBIDDEN",
    "Message": "Project access required"
  }
}
429 Too Many Requests

Too Many Requests. The response includes a Retry-After header with the number of seconds to wait before retrying.

Headers

  • X-Trace-ID string

    Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

    Example
    abc123def456ghi789
  • Retry-After integer

    Number of seconds to wait before retrying the request. Present on 429 responses.

    Example
    30
    Limits
    min 1

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

    Error detail containing a machine-readable code and human-readable message.

    3 fields
    • Code string required

      Machine-readable error code for programmatic handling.

      Example
      FORBIDDEN
    • Message string required

      Human-readable error message.

      Example
      Project access required
    • Fields array of object FieldError

      Field-level validation errors. Only present for VALIDATION_ERROR responses.

      Each item

      A single field-level validation error.

      4 fields
      • Field string required

        Name of the field that failed validation.

        Example
        Name
      • Message string required

        Human-readable validation error message for this field.

        Example
        Name cannot be empty
      • Code string

        Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

        Values
        REQUIRED TOO_LONG TOO_SHORT OUT_OF_RANGE TOO_MANY INVALID_FORMAT NOT_ALLOWED CONFLICT INVALID_ENCODING INSECURE_SCHEME UNSAFE_CONTENT REQUIRED_WHEN_ENABLED
        Example
        TOO_LONG
      • Params map of string to any

        Machine-readable values the message is built from, such as limits or allowed values. Keys are PascalCase; which keys are present depends on Code. Optional.

        Example
        {
          "Max": 100
        }
Example response: Limit exceeded
{
  "Error": {
    "Code": "RATE_LIMIT_EXCEEDED",
    "Message": "Rate limit exceeded. Retry after the number of seconds in the Retry-After header."
  }
}
500 Internal Server Error

Internal Server Error - Unexpected server error. Include the X-Trace-ID header value when contacting support.

Headers

  • X-Trace-ID string

    Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

    Example
    abc123def456ghi789

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

    Error detail containing a machine-readable code and human-readable message.

    3 fields
    • Code string required

      Machine-readable error code for programmatic handling.

      Example
      FORBIDDEN
    • Message string required

      Human-readable error message.

      Example
      Project access required
    • Fields array of object FieldError

      Field-level validation errors. Only present for VALIDATION_ERROR responses.

      Each item

      A single field-level validation error.

      4 fields
      • Field string required

        Name of the field that failed validation.

        Example
        Name
      • Message string required

        Human-readable validation error message for this field.

        Example
        Name cannot be empty
      • Code string

        Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

        Values
        REQUIRED TOO_LONG TOO_SHORT OUT_OF_RANGE TOO_MANY INVALID_FORMAT NOT_ALLOWED CONFLICT INVALID_ENCODING INSECURE_SCHEME UNSAFE_CONTENT REQUIRED_WHEN_ENABLED
        Example
        TOO_LONG
      • Params map of string to any

        Machine-readable values the message is built from, such as limits or allowed values. Keys are PascalCase; which keys are present depends on Code. Optional.

        Example
        {
          "Max": 100
        }
Example response: Internal server error
{
  "Error": {
    "Code": "INTERNAL_ERROR",
    "Message": "Internal error"
  }
}