Suomi.fi

Suomi.fi Service collection API

Service collections are used to group [services](#tag/service) and [service channels](#tag/service-channel) together to create thematic groups.

Documentation GitHub OpenAPI

Operations 3

GET /api/v12/service-collection/{contentId} By content id #

GET /api/v12/service-collection/search Search service collections #

GET /api/v12/service-collection/archived Get archived service collections #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/suomi-fi:suomi-fi-service-collection-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Suomi Fi Service collection API
  version: 0.1.0
  description: 'Operations tagged Service collection across 2 of this provider''s published API definitions: suomi-fi-ptv-v12-openapi.json, suomi-fi-ptv-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api-gw.palvelutietovaranto.suomi.fi
  description: Development server
tags:
- name: Service collection
  description: 'Service collections are used to group services and service channels together

    to create thematic groups.'
paths:
  /api/v12/service-collection/{contentId}:
    get:
      operationId: getServiceCollection
      summary: By content id
      tags:
      - Service collection
      parameters:
      - schema:
          $ref: '#/components/schemas/ContentIdType'
        in: path
        name: contentId
        required: true
      security:
      - apiKeyHeader: []
      responses:
        '200':
          description: Service collection response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceCollectionResponse'
        '400':
          description: Problem details response with errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetailsWithErrorsType'
        '404':
          description: Problem details response for 404 errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetailsNotFoundType'
        '500':
          description: Problem details response type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetailsType'
    servers:
    - url: https://api-gw.palvelutietovaranto.suomi.fi
      description: Development server
  /api/v12/service-collection/search:
    get:
      operationId: searchServiceCollections
      summary: Search service collections
      tags:
      - Service collection
      parameters:
      - schema:
          type: integer
          minimum: 1
          maximum: 1000000
          default: 1
        in: query
        name: page
        required: true
        description: Pagination page
      - schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
        in: query
        name: pageSize
        required: true
        description: Pagination page size
      - schema:
          type: array
          items:
            $ref: '#/components/schemas/ContentIdType'
          maxItems: 20
          uniqueItems: true
        in: query
        name: organizationContentIds
        required: false
        description: Filter by comma separated list of [organization](#tag/organization) content id:s
      - schema:
          $ref: '#/components/schemas/DateTime'
        in: query
        name: publishedAtOrAfter
        required: false
      security:
      - apiKeyHeader: []
      responses:
        '200':
          description: Service collection search response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceCollectionSearchResponse'
        '400':
          description: Problem details response with errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetailsWithErrorsType'
        '500':
          description: Problem details response type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetailsType'
    servers:
    - url: https://api-gw.palvelutietovaranto.suomi.fi
      description: Development server
  /api/v12/service-collection/archived:
    get:
      operationId: archivedServiceCollections
      summary: Get archived service collections
      tags:
      - Service collection
      parameters:
      - schema:
          type: integer
          minimum: 1
          maximum: 1000000
          default: 1
        in: query
        name: page
        required: true
        description: Pagination page
      - schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
        in: query
        name: pageSize
        required: true
        description: Pagination page size
      - schema:
          type: array
          items:
            $ref: '#/components/schemas/ContentIdType'
          maxItems: 20
          uniqueItems: true
        in: query
        name: organizationContentIds
        required: false
        description: Filter by comma separated list of [organization](#tag/organization) content id:s
      - schema:
          $ref: '#/components/schemas/DateTime'
        in: query
        name: archivedAtOrAfter
        required: true
      security:
      - apiKeyHeader: []
      responses:
        '200':
          description: Archived entities response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArchivedEntitiesResponse'
        '400':
          description: Problem details response with errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetailsWithErrorsType'
        '500':
          description: Problem details response type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetailsType'
    servers:
    - url: https://api-gw.palvelutietovaranto.suomi.fi
      description: Development server
components:
  schemas:
    ProblemDetailsStatusCode:
      type: integer
      description: Status code
      title: ProblemDetailsStatusCode
    ArchivedEntityResponse:
      type: object
      required:
      - contentId
      properties:
        contentId:
          $ref: '#/components/schemas/ContentIdType'
      description: Archived entity response
      title: ArchivedEntityResponse
    ProblemDetailsErrorType:
      type: string
      description: Type of the error
      title: ProblemDetailsErrorType
    ServiceCollectionResponse:
      type: object
      required:
      - contentId
      - organizationContentId
      - languageVersions
      - publishedAt
      - items
      properties:
        migratedAt:
          anyOf:
          - $ref: '#/components/schemas/DateTime'
          - type: 'null'
        contentId:
          $ref: '#/components/schemas/ContentIdType'
        organizationContentId:
          $ref: '#/components/schemas/ContentIdType'
        languageVersions:
          $ref: '#/components/schemas/ServiceCollectionLanguageVersionsResponse'
        publishedAt:
          anyOf:
          - $ref: '#/components/schemas/DateTime'
          - type: 'null'
        items:
          type: array
          items:
            $ref: '#/components/schemas/ServiceCollectionItem'
      description: Service collection response
      title: ServiceCollectionResponse
    NotFoundStatusType:
      anyOf:
      - type: string
        enum:
        - NotPublished
      - type: string
        enum:
        - Unknown
      description: Not found status type
      title: NotFoundStatusType
    ArchivedEntitiesResponse:
      type: object
      required:
      - page
      - pageSize
      - totalItems
      - totalPages
      - items
      properties:
        page:
          type: integer
          description: Pagination current page
        pageSize:
          type: integer
          description: Pagination current page size
        totalItems:
          type: integer
          description: Total items found
        totalPages:
          type: integer
          description: Total number of pages
        items:
          type: array
          items:
            $ref: '#/components/schemas/ArchivedEntityResponse'
      description: Archived entities response
      title: ArchivedEntitiesResponse
    ProblemDetailsInstance:
      type: string
      description: Request instance (url)
      title: ProblemDetailsInstance
    ProblemDetailsNotFoundType:
      type: object
      required:
      - title
      - detail
      - status
      - type
      - requestId
      - instance
      - reason
      properties:
        title:
          type: string
          description: Problem details response title
        detail:
          $ref: '#/components/schemas/ProblemDetailsDetail'
        status:
          $ref: '#/components/schemas/ProblemDetailsStatusCode'
        type:
          $ref: '#/components/schemas/ProblemDetailsErrorType'
        requestId:
          $ref: '#/components/schemas/ProblemDetailsRequestId'
        instance:
          $ref: '#/components/schemas/ProblemDetailsInstance'
        reason:
          $ref: '#/components/schemas/NotFoundStatusType'
      description: Problem details response for 404 errors
      title: ProblemDetailsNotFoundType
    ContentIdType:
      type: string
      format: uuid
      description: Content id type
      title: ContentIdType
    ProblemDetailsType:
      type: object
      required:
      - title
      - detail
      - status
      - type
      - requestId
      - instance
      properties:
        title:
          type: string
          description: Problem details response title
        detail:
          $ref: '#/components/schemas/ProblemDetailsDetail'
        status:
          $ref: '#/components/schemas/ProblemDetailsStatusCode'
        type:
          $ref: '#/components/schemas/ProblemDetailsErrorType'
        requestId:
          $ref: '#/components/schemas/ProblemDetailsRequestId'
        instance:
          $ref: '#/components/schemas/ProblemDetailsInstance'
      description: Problem details response type
      title: ProblemDetailsType
    ProblemDetailsRequestId:
      type: string
      description: Request identifier
      title: ProblemDetailsRequestId
    ProblemDetailsDetail:
      type: string
      description: Error details
      title: ProblemDetailsDetail
    ValidationErrorType:
      type: object
      required:
      - message
      properties:
        path:
          type: string
          description: Validation error path
        message:
          type: string
          description: Error message
      description: Validation error type
      title: ValidationErrorType
    ServiceCollectionItem:
      type: object
      required:
      - itemType
      - contentId
      properties:
        itemType:
          enum:
          - Service
          - ServiceChannel
          type: string
        contentId:
          $ref: '#/components/schemas/ContentIdType'
      additionalProperties: false
      description: Service collection item
      title: ServiceCollectionItem
    ProblemDetailsWithErrorsType:
      type: object
      required:
      - title
      - detail
      - status
      - type
      - requestId
      - instance
      - errors
      properties:
        title:
          type: string
          description: Problem details response title
        detail:
          $ref: '#/components/schemas/ProblemDetailsDetail'
        status:
          $ref: '#/components/schemas/ProblemDetailsStatusCode'
        type:
          $ref: '#/components/schemas/ProblemDetailsErrorType'
        requestId:
          $ref: '#/components/schemas/ProblemDetailsRequestId'
        instance:
          $ref: '#/components/schemas/ProblemDetailsInstance'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ValidationErrorType'
      description: Problem details response with errors
      title: ProblemDetailsWithErrorsType
    ServiceCollectionSearchResponse:
      type: object
      required:
      - page
      - pageSize
      - totalItems
      - totalPages
      - items
      properties:
        page:
          type: integer
          description: Pagination current page
        pageSize:
          type: integer
          description: Pagination current page size
        totalItems:
          type: integer
          description: Total items found
        totalPages:
          type: integer
          description: Total number of pages
        items:
          type: array
          items:
            $ref: '#/components/schemas/ServiceCollectionResponse'
      description: Service collection search response
      title: ServiceCollectionSearchResponse
    ServiceCollectionLanguageVersionsResponse:
      type: object
      properties:
        fi:
          $ref: '#/components/schemas/ServiceCollectionLanguageVersionResponse'
        sv:
          $ref: '#/components/schemas/ServiceCollectionLanguageVersionResponse'
        en:
          $ref: '#/components/schemas/ServiceCollectionLanguageVersionResponse'
        se:
          $ref: '#/components/schemas/ServiceCollectionLanguageVersionResponse'
        smn:
          $ref: '#/components/schemas/ServiceCollectionLanguageVersionResponse'
        sms:
          $ref: '#/components/schemas/ServiceCollectionLanguageVersionResponse'
      additionalProperties: false
      description: Service collection language version response
      title: ServiceCollectionLanguageVersionsResponse
    DateTime:
      type: string
      format: date-time
      description: string, e.g. 2025-09-22T07:32:52.026Z
      title: DateTime
    ServiceCollectionLanguageVersionResponse:
      type: object
      required:
      - name
      - summary
      - description
      properties:
        name:
          type: string
        summary:
          anyOf:
          - type: string
          - type: 'null'
        description:
          anyOf:
          - type: string
            description: Markdown-formatted content. Use a Markdown parser/renderer when presenting it.
          - type: 'null'
      description: Service collection language version response
      title: ServiceCollectionLanguageVersionResponse
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer auth
    apiKeyHeader:
      name: x-api-key
      in: header
      description: API-key auth
      type: apiKey
externalDocs:
  url: https://kehittajille.suomi.fi/palvelut/palvelutietovaranto/rajapinta-ja-arkkitehtuuriuudistus
  description: PTV - Suomi.fi Service developers documentation
x-refined-from:
- suomi-fi-ptv-v12-openapi.json
- suomi-fi-ptv-openapi.yml
x-tagGroups:
- name: Core
  tags:
  - Service channel
  - Connection
  - General description
  - Organization
  - Service
  - Service collection
- name: Reference data
  tags:
  - Languages
  - Countries
  - Municipalities
  - Regions
  - Wellbeing services counties
  - Postal codes
  - Industrial classes
  - Life events
  - Ontology terms
  - Service classes
  - Target groups
- name: Infrastructure
  tags:
  - Health check

Suomi.fi Service collection API

Operations 3

Documentation

Specifications

Schemas & Data

Other Resources