> ## Documentation Index > Fetch the complete documentation index at: https://docs.punchplay.tv/llms.txt > Use this file to discover all available pages before exploring further. # Get title metadata and scope-dependent user state > Private fields are returned only when the token also has ratings:read, history:read, lists:read, or collection:read. ## OpenAPI ````yaml /openapi.yaml get /api/platform/v1/title/{type}/{id} openapi: 3.1.0 info: title: PunchPlay API version: 1.0.0-beta.3 description: >- Complete beta contract for native and third-party clients, plus the stable read-only public profile API. OAuth access tokens use explicit per-operation scopes. summary: Platform and public API surface for PunchPlay developers. servers: - url: https://punchplay.tv description: Production - url: http://localhost:3000 description: Local development security: [] tags: - name: Authentication - name: Profile - name: Titles - name: History - name: Ratings - name: Lists - name: Collection - name: Playback - name: Calendar - name: Community - name: Notifications - name: Trophies - name: Public Catalog - name: Public Users paths: /api/platform/v1/title/{type}/{id}: parameters: - $ref: '#/components/parameters/TitleType' - $ref: '#/components/parameters/SourceId' get: tags: - Titles summary: Get title metadata and scope-dependent user state description: >- Private fields are returned only when the token also has ratings:read, history:read, lists:read, or collection:read. operationId: getTitle parameters: - in: query name: region schema: type: string minLength: 2 maxLength: 2 - in: query name: scope schema: type: string enum: - title - series - season - episode responses: '200': $ref: '#/components/responses/TitleDetailSuccess' '400': $ref: '#/components/responses/ApiError' '401': $ref: '#/components/responses/ApiError' '403': $ref: '#/components/responses/ApiError' '404': $ref: '#/components/responses/ApiError' '429': $ref: '#/components/responses/ApiError' security: - oauth2: - profile:read components: parameters: TitleType: in: path name: type required: true schema: type: string enum: - movie - show SourceId: in: path name: id required: true schema: type: integer minimum: 1 responses: TitleDetailSuccess: description: Title detail content: application/json: schema: $ref: '#/components/schemas/TitleDetailResponse' headers: X-RateLimit-Limit: schema: type: integer description: Ceiling of the most constraining bucket for this request. X-RateLimit-Remaining: schema: type: integer description: Requests remaining in the current window. X-RateLimit-Reset: schema: type: integer description: Unix time in seconds when the current window resets. ApiError: description: API error headers: X-PunchPlay-Request-Id: schema: type: string X-RateLimit-Limit: schema: type: integer description: Ceiling of the most constraining bucket for this request. X-RateLimit-Remaining: schema: type: integer description: Requests remaining in the current window. X-RateLimit-Reset: schema: type: integer description: Unix time in seconds when the current window resets. content: application/json: schema: $ref: '#/components/schemas/ApiError' schemas: TitleDetailResponse: type: object required: - title - interaction - watchHistory - userLists - collectionStatus - featuredLists - communityRating - externalRatings properties: title: $ref: '#/components/schemas/NativeTitle' interaction: oneOf: - $ref: '#/components/schemas/TitleInteraction' - type: 'null' watchHistory: type: array items: type: object additionalProperties: true userLists: oneOf: - type: array items: $ref: '#/components/schemas/TitleUserList' - type: 'null' collectionStatus: oneOf: - type: object required: - owned - formats - items properties: owned: type: boolean formats: type: array items: type: string items: type: array items: type: object required: - id - format - season properties: id: type: integer format: type: string season: type: integer additionalProperties: false additionalProperties: false - type: 'null' featuredLists: type: array items: type: object additionalProperties: true communityRating: type: object required: - average - count properties: average: type: - number - 'null' count: type: integer minimum: 0 additionalProperties: false externalRatings: oneOf: - type: object required: - ratings properties: ratings: type: array items: type: object additionalProperties: true additionalProperties: false - type: 'null' additionalProperties: false ApiError: type: object required: - error - message - request_id properties: error: type: string message: type: string request_id: type: - string - 'null' required_scope: type: string additionalProperties: true NativeTitle: type: object required: - tmdbId - type - category - isAnime - name - year - overview - posterUrl - backdropUrl - communityRating - genres properties: tmdbId: type: integer minimum: 1 type: type: string enum: - movie - show category: type: string enum: - movie - show - anime isAnime: type: boolean name: type: string tagline: type: string year: type: integer releaseDate: type: string overview: type: string posterUrl: type: string backdropUrl: type: string communityRating: type: number genres: type: array items: type: string originalLanguage: type: string status: type: string ageRating: type: string runtimeMinutes: type: integer episodeRunTimeMinutes: type: integer seasonsCount: type: integer episodesCount: type: integer seasonStats: type: array items: type: object additionalProperties: true recommendations: type: array items: type: object additionalProperties: true additionalProperties: true TitleInteraction: type: object required: - watchedAt - rating - isFavourite - showStatus properties: watchedAt: type: - string - 'null' format: date-time rating: type: - number - 'null' isFavourite: type: boolean showStatus: type: - string - 'null' additionalProperties: false TitleUserList: type: object required: - id - name - description - isPublic - isWatchlist - isDynamicList - lastSyncedAt - isCollaborative - isFeatured - ownerUsername - itemCount - itemBreakdown - createdAt - previewPosters - containsItemId properties: id: type: integer minimum: 1 name: type: string description: type: - string - 'null' isPublic: type: boolean isWatchlist: type: boolean isDynamicList: type: boolean lastSyncedAt: type: - string - 'null' format: date-time isCollaborative: type: boolean isFeatured: type: boolean ownerUsername: type: - string - 'null' itemCount: type: integer minimum: 0 itemBreakdown: type: object required: - movies - shows - anime properties: movies: type: integer minimum: 0 shows: type: integer minimum: 0 anime: type: integer minimum: 0 additionalProperties: false createdAt: type: string format: date-time previewPosters: type: array items: $ref: '#/components/schemas/ListPreviewPoster' containsItemId: type: - integer - 'null' minimum: 1 additionalProperties: false ListPreviewPoster: type: object required: - posterPath - tmdbId - type properties: posterPath: type: string tmdbId: type: integer minimum: 1 type: type: string enum: - movie - show securitySchemes: oauth2: type: oauth2 flows: authorizationCode: authorizationUrl: /api/platform/v1/oauth/authorize tokenUrl: /api/platform/v1/oauth/token scopes: profile:read: Read basic profile and title metadata history:read: Read watch history history:write: Log, edit, and delete watches lists:read: Read lists lists:write: Create and edit lists ratings:read: Read ratings, favourites, and statuses ratings:write: Rate, favourite, and change statuses collection:read: Read collection items collection:write: Add and remove collection items notifications:read: Read notifications and notification preferences notifications:write: Manage notification read state and preferences trophies:read: Read trophy progress profile:write: Update profile details and preferences playback:read: Read playback and continue-watching state playback:write: Update playback state events:read: Subscribe to playback events ````