> ## Documentation Index
> Fetch the complete documentation index at: https://kb.aampe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get surface content

> Returns one result per surface that could be resolved, in the same order as requested.
Surfaces that cannot be resolved are omitted from the list.



## OpenAPI

````yaml /api-guide/content-openapi.json get /v1/surface/content
openapi: 3.1.0
info:
  title: Content API
  description: >-
    The Content API returns personalized surface content for your users in real
    time. Use it to fetch content for the surfaces (placements) you configure in
    Aampe.


    **Base URL:** `https://content.{region}.api.aampe.com`


    **Regions:** `us-east1` | `europe-west3` | `asia-southeast1`


    **Authentication:** `X-API-Key: <Content API key>` header. Keys are per
    customer.


    Further documentation: [https://kb.aampe.com](https://kb.aampe.com)
  version: 1.0.0
servers:
  - url: https://content.{region}.api.aampe.com
    description: Regional Content API — set region for Try it out.
    variables:
      region:
        default: us-east1
        enum:
          - us-east1
          - europe-west3
          - asia-southeast1
        description: Deploy region for your Content API tenant
security: []
externalDocs:
  description: Aampe knowledge base
  url: https://kb.aampe.com
paths:
  /v1/surface/content:
    get:
      tags:
        - Surface
      summary: Get surface content
      description: >-
        Returns one result per surface that could be resolved, in the same order
        as requested.

        Surfaces that cannot be resolved are omitted from the list.
      operationId: get_surface_content_v1_surface_content_get
      parameters:
        - name: contact_id
          in: query
          required: true
          schema:
            type: string
            title: Contact ID
            description: The ID of the user for which you want to retrieve content.
          description: The ID of the user for which you want to retrieve content.
        - name: surface_id
          in: query
          required: true
          schema:
            type: array
            items:
              type: string
              format: uuid
            title: Surface IDs
            description: >-
              The UUID v4 IDs of the surfaces for which you want to retrieve
              content.
          description: >-
            The UUID v4 IDs of the surfaces for which you want to retrieve
            content.
        - name: allow_unassigned
          in: query
          required: false
          schema:
            type: boolean
            title: Allow unassigned surfaces
            description: >-
              When true, surfaces without personalized content for this user may
              still return a default variant from Aampe. When false, those
              surfaces are skipped; the API returns 404 if no requested surface
              can be returned.
            default: false
          description: >-
            When true, surfaces without personalized content for this user may
            still return a default variant from Aampe. When false, those
            surfaces are skipped; the API returns 404 if no requested surface
            can be returned.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SurfaceContentResponse'
                title: Response Get Surface Content V1 Surface Content Get
        '401':
          description: Invalid or missing `X-API-Key`, or key could not be validated.
        '404':
          description: >-
            None of the requested surfaces could be returned with the current
            parameters (for example, no content available and fallback
            disabled).
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    SurfaceContentResponse:
      properties:
        surface_id:
          type: string
          format: uuid
          title: Surface Id
          description: UUID v4 id for the surface
          example: eb223fbc-9065-4ff0-ae2a-c47c623bff07
        assignment_id:
          type: string
          format: uuid
          title: Assignment Id
          description: Identifier for this content assignment in the response.
          example: 2ceb1da8-b6f7-4089-b55d-5ba743389cea
        n_alternates:
          type: integer
          title: N Alternates
          description: Total number of alternates.
          example: 1
        control:
          $ref: '#/components/schemas/SurfaceControl'
        alternates:
          items:
            $ref: '#/components/schemas/SurfaceAlternate'
          type: array
          title: Alternates
      type: object
      required:
        - surface_id
        - assignment_id
        - n_alternates
        - control
        - alternates
      title: SurfaceContentResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SurfaceControl:
      properties:
        min_gap_days:
          type: integer
          title: Min Gap Days
          description: Gap in between
          example: 1
      type: object
      required:
        - min_gap_days
      title: SurfaceControl
    SurfaceAlternate:
      properties:
        alternate_assignment_id:
          type: string
          title: Alternate Assignment Id
          description: Identifier for this alternate.
          example: 226b4d62-c25b-41bf-b45b-fd3d65120091
      additionalProperties: true
      type: object
      required:
        - alternate_assignment_id
      title: SurfaceAlternate
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key

````