REST APIs for Confluent Manager for Apache Flink

You can use the Confluent REST API to manage these resources for Confluent Manager for Apache Flink® (CMF):

  • Environments
  • Applications

In addition to the REST API, you can manage the above resources by using these Confluent tools:

Prerequisites

The REST API requires networked access to CMF.

As part of the installation process, a Kubernetes service is created that exposes CMF behind an outward-facing endpoint. By default, the service exposes CMF on port 8080.

If you have configured authentication and/or authorization, each API request must be authenticated and you need permissions on the respective resource.

For more information, see:

Endpoints (v1)

All endpoints are served under /cmf/api/v1.

Identifiers

All resources are identified by name. Each name must be unique in its scope and follow the following restrictions:

  • Minimum length: 4
  • Maximum length: 253
  • Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

Timestamps

All timestamps in fields named metadata.creationTimestamp and metadata.updateTimestamp and the created_time and updated_time fields in the Environment are RFC 3339 formatted strings, compatible with Java’s Instant type.

The timestamp is in UTC, and does not contain any timezone information.name

This is an example: 2025-03-31T11:34:01.503Z.

Example usage with curl

The following example shows how to create a Flink Application in an environment called “test” using curl:

Contents of the file flink-application.yaml:

apiVersion: cmf.confluent.io/v1
kind: FlinkApplication
metadata:
  name: curl-example
spec:
  image: confluentinc/cp-flink:1.19.1-cp2
  flinkVersion: v1_19
  flinkConfiguration:
    taskmanager.numberOfTaskSlots: "1"
  serviceAccount: flink
  jobManager:
    resource:
      memory: 1048m
      cpu: 1
  taskManager:
    resource:
      memory: 1048m
      cpu: 1
  job:
    jarURI: local:///opt/flink/examples/streaming/StateMachineExample.jar
    state: running
    parallelism: 3
    upgradeMode: stateless

Submission using curl, assuming CMF is running on localhost:8080:

curl -H "Content-type: application/yaml" --data-binary "@flink-application.yaml" localhost:8080/cmf/api/v1/environments/test/applications

API reference

This section contains the REST API reference for Confluent Manager for Apache Flink® and the API spec.

View the API spec

If you want to see the entire API spec, you can view the YAML file in the expanding section below.

View the entire YAML specification file
# Naming conventions:
# - Post*: Schemas for POST requests
# - Get*: Schemas for GET requests
# Good resources:
# - Spring Petclinic: https://github.com/spring-petclinic/spring-petclinic-rest/blob/master/src/main/resources/openapi.yml
openapi: 3.0.1
info:
  title: Confluent Manager for Apache Flink / CMF
  description: Apache Flink job lifecycle management component for Confluent Platform.
  version: '1.0'
servers:
  - url: http://localhost:8080/cmf/api/v1
paths:
  /environments:
    post:
      operationId: createOrUpdateEnvironment
      summary: Create or update an Environment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostEnvironment'
        required: true
      responses:
        201:
          description: The Environment was successfully created or updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Environment'
        400:
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestError'
        500:
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestError'
    get:
      operationId: getEnvironments
      summary: Retrieve a paginated list of all environments.
      x-spring-paginated: true
      parameters:
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/sizeParam'
        - $ref: '#/components/parameters/sortParam'
      responses:
        200:
          description: List of environments found. If no environments are found, an empty list is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvironmentsPage'
        304:
          description: Not modified.
          headers:
            ETag:
              description: An ID for this version of the response.
              schema:
                type: string
        500:
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestError'
  /environments/{envName}:
    get:
      operationId: getEnvironment
      summary: Get/Describe an environment with the given name.
      parameters:
        - name: envName
          in: path
          description: Name of the Environment to be retrieved.
          required: true
          schema:
            type: string
      responses:
        200:
          description: Environment found and returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Environment'
        404:
          description: Environment not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestError'
        500:
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestError'
    delete:
      operationId: deleteEnvironment
      parameters:
        - name: envName
          in: path
          description: Name of the Environment to be deleted.
          required: true
          schema:
            type: string
      responses:
        200:
          description: Environment found and deleted.
        304:
          description: Not modified.
        500:
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestError'
        404:
          description: Environment not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestError'
  /environments/{envName}/applications:
    post:
      operationId: createOrUpdateApplication
      summary: Creates a new Flink Application or updates an existing one in the given Environment.
      parameters:
        - name: envName
          in: path
          description: Name of the Environment
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Application'
          application/yaml:
            schema:
              $ref: '#/components/schemas/Application'
        required: true
      responses:
        201:
          description: The Application was successfully created or updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
            application/yaml:
              schema:
                $ref: '#/components/schemas/Application'
        400:
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestError'
        422:
          description: Request valid but invalid content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestError'
        500:
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestError'
    get:
      operationId: getApplications
      summary: Retrieve a paginated list of all applications in the given Environment.
      x-spring-paginated: true
      parameters:
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/sizeParam'
        - $ref: '#/components/parameters/sortParam'
        - name: envName
          in: path
          description: Name of the Environment
          required: true
          schema:
            type: string
      responses:
        200:
          description: Application found and returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationsPage'
        304:
          description: Not modified.
          headers:
            ETag:
              description: An ID for this version of the response.
              schema:
                type: string
        500:
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestError'
  /environments/{envName}/applications/{appName}:
    get:
      operationId: getApplication
      summary: Retrieve an Application of the given name in the given Environment.
      parameters:
        - name: envName
          in: path
          description: Name of the Environment
          required: true
          schema:
            type: string
        - name: appName
          in: path
          description: Name of the Application
          required: true
          schema:
            type: string
      responses:
        200:
          description: Application found and returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        304:
          description: Not modified.
          headers:
            ETag:
              description: An ID for this version of the response.
              schema:
                type: string
        500:
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestError'
        404:
          description: Application not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestError'
    delete:
      operationId: deleteApplication
      summary: Deletes an Application of the given name in the given Environment.
      parameters:
        - name: envName
          in: path
          description: Name of the Environment
          required: true
          schema:
            type: string
        - name: appName
          in: path
          description: Name of the Application
          required: true
          schema:
            type: string
      responses:
        200:
          description: Application found and deleted.
        304:
          description: Not modified.
        500:
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestError'

  /environments/{envName}/applications/{appName}/start:
    post:
      operationId: startApplication
      summary: Starts an earlier submitted Flink Application
      parameters:
        - name: envName
          in: path
          description: Name of the Environment
          required: true
          schema:
            type: string
        - name: appName
          in: path
          description: Name of the Application
          required: true
          schema:
            type: string
      responses:
        200:
          description: Application started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        304:
          description: Not modified.
        500:
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestError'
  /environments/{envName}/applications/{appName}/suspend:
    post:
      operationId: suspendApplication
      summary: Suspends an earlier started Flink Application
      parameters:
        - name: envName
          in: path
          description: Name of the Environment
          required: true
          schema:
            type: string
        - name: appName
          in: path
          description: Name of the Application
          required: true
          schema:
            type: string
      responses:
        200:
          description: Application suspended
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        304:
          description: Not modified.
        500:
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestError'

components:
  # https://github.com/daniel-shuy/swaggerhub-spring-pagination / Copyright (c) 2023 Daniel Shuy
  parameters:
    pageParam:
      in: query
      name: page
      schema:
        type: integer
      description: Zero-based page index (0..N)
    sizeParam:
      in: query
      name: size
      schema:
        type: integer
      description: The size of the page to be returned
    sortParam:
      in: query
      name: sort
      schema:
        type: array
        items:
          type: string
      description: >-
        Sorting criteria in the format: property,(asc|desc). Default sort order is ascending.
        Multiple sort criteria are supported.
  schemas:
    #
    # Shared utilities
    #
    RestError:
      title: REST Error
      description: The schema for all error responses.
      type: object
      properties:
        errors:
          title: errors
          description: List of all errors
          type: array
          items:
            title: error
            type: object
            description: An error
            properties:
              message:
                type: string
                description: An error message
    PaginationResponse:
      type: object
      properties:
        pageable:
          $ref: '#/components/schemas/Pageable'
    Sort:
      type: object
      format: sort
      properties:
        sorted:
          type: boolean
          description: Whether the results are sorted.
          example: true
        unsorted:
          type: boolean
          description: Whether the results are unsorted.
          example: false
        empty:
          type: boolean
    Pageable:
      type: object
      format: pageable
      properties:
        page:
          type: integer
          minimum: 0
        size:
          type: integer
          description: The number of items in a page.
          minimum: 1
        sort:
          $ref: '#/components/schemas/Sort'

    #
    # Shared Bases
    #
    PostResourceBase:
      type: object
      properties:
        name:
          title: Name
          description: A unique name for the resource.
          type: string
          # Validate for DNS subdomain name
          minLength: 4
          maxLength: 253
          pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$'
    GetResourceBase:
      type: object
      properties:
        created_time:
          title: Time when the resource has been created
          type: string
          format: date-time
        updated_time:
          title: Time when the resource has been last updated
          type: string
          format: date-time
    # defines kubernetesNamespace
    KubernetesNamespace:
      type: object
      properties:
        kubernetesNamespace:
          type: string
          title: Kubernetes namespace name where resources referencing this environment are created in.
          minLength: 1
          maxLength: 253
          pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$'
    # defines properties of fields with flinkApplicationDefaults
    ResourceWithFlinkApplicationDefaults:
      type: object
      properties:
        flinkApplicationDefaults:
          title: the defaults as YAML or JSON for FlinkApplications
          type: object
          format: yamlorjson

    #################### Request Schema ####################
    PostEnvironment:
      title: Environment
      description: Environment
      type: object
      required:
        - name
      allOf:
        - $ref: '#/components/schemas/PostResourceBase'
        - $ref: '#/components/schemas/ResourceWithFlinkApplicationDefaults'
        - $ref: '#/components/schemas/KubernetesNamespace'


    #################### Response Schema ####################
    Environment:
      title: Environment
      description: Environment
      type: object
      allOf:
        - $ref: '#/components/schemas/PostResourceBase'
        - $ref: '#/components/schemas/GetResourceBase'
        - $ref: '#/components/schemas/ResourceWithFlinkApplicationDefaults'
        - $ref: '#/components/schemas/KubernetesNamespace'
      required:
        - name
        - kubernetesNamespace
    EnvironmentsPage:
      type: object
      allOf:
        - $ref: '#/components/schemas/PaginationResponse'
        - type: object
          properties:
            metadata:
              type: object
              title: EnvironmentsPageMetadata
              properties:
                size:
                  type: integer
                  format: int64
                  default: 0
            items:
              type: array
              title: "Env"
              items:
                $ref: '#/components/schemas/Environment'
              default: [ ]
    Application:
      title: Application
      description: Represents a Flink Application submitted by the user
      type: object
      properties:
        apiVersion:
          title: API version for Application spec
          type: string
        kind:
          title: Kind of resource - set to FlinkApplication
          type: string
        metadata:
          title: Metadata about the application
          type: object
          format: yamlorjson
        spec:
          title: Spec for Flink Application
          type: object
          format: yamlorjson
        status:
          title: Status for Flink Application
          type: object
          format: yamlorjson
      required: # status is optional for application spec
        - metadata
        - kind
        - spec
        - apiVersion
    ApplicationsPage:
      type: object
      allOf:
        - $ref: '#/components/schemas/PaginationResponse'
        - type: object
          properties:
            metadata:
              type: object
              title: ApplicationPageMetadata
              properties:
                size:
                  type: integer
                  format: int64
                  default: 0
            items:
              type: array
              items:
                $ref: '#/components/schemas/Application'
              default: [ ]

Reference details

POST /environments

Create or update an Environment

Example request:

POST /environments HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "string",
    "flinkApplicationDefaults": {},
    "kubernetesNamespace": "string"
}
Status Codes:
  • 201 Created –

    The Environment was successfully created or updated.

    Example response:

    HTTP/1.1 201 Created
Content-Type: application/json

{
    "name": "string",
    "created_time": "2025-05-17T00:45:00.827686",
    "updated_time": "2025-05-17T00:45:00.827686",
    "flinkApplicationDefaults": {},
    "kubernetesNamespace": "string"
}
  • 400 Bad Request –

    Bad request.

    Example response:

    HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "errors": [
        {
            "message": "string"
        }
    ]
}
  • 500 Internal Server Error –

    Server error.

    Example response:

    HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "errors": [
        {
            "message": "string"
        }
    ]
}
GET /environments

Retrieve a paginated list of all environments.

Query Parameters:
 
  • page (integer) – Zero-based page index (0..N)
  • size (integer) – The size of the page to be returned
  • sort (array) – Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.

Example request:

GET /environments HTTP/1.1
Host: example.com
Status Codes:
  • 200 OK –

    List of environments found. If no environments are found, an empty list is returned.

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "pageable": {
        "page": 1,
        "size": 1,
        "sort": {
            "sorted": true,
            "unsorted": true,
            "empty": true
        }
    },
    "metadata": {
        "size": 1
    },
    "items": [
        {
            "name": "string",
            "created_time": "2025-05-17T00:45:00.827686",
            "updated_time": "2025-05-17T00:45:00.827686",
            "flinkApplicationDefaults": {},
            "kubernetesNamespace": "string"
        }
    ]
}
  • 304 Not Modified – Not modified.
  • 500 Internal Server Error –

    Server error.

    Example response:

    HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "errors": [
        {
            "message": "string"
        }
    ]
}
Response Headers:
 
  • ETag – An ID for this version of the response.
GET /environments/{envName}

Get/Describe an environment with the given name.

Parameters:
  • envName (string) – Name of the Environment to be retrieved.

Example request:

GET /environments/{envName} HTTP/1.1
Host: example.com
Status Codes:
  • 200 OK –

    Environment found and returned.

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "name": "string",
    "created_time": "2025-05-17T00:45:00.827686",
    "updated_time": "2025-05-17T00:45:00.827686",
    "flinkApplicationDefaults": {},
    "kubernetesNamespace": "string"
}
  • 404 Not Found –

    Environment not found.

    Example response:

    HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "errors": [
        {
            "message": "string"
        }
    ]
}
  • 500 Internal Server Error –

    Server error.

    Example response:

    HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "errors": [
        {
            "message": "string"
        }
    ]
}
DELETE /environments/{envName}
Parameters:
  • envName (string) – Name of the Environment to be deleted.
Status Codes:
  • 200 OK – Environment found and deleted.
  • 304 Not Modified – Not modified.
  • 500 Internal Server Error –

    Server error.

    Example response:

    HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "errors": [
        {
            "message": "string"
        }
    ]
}
  • 404 Not Found –

    Environment not found.

    Example response:

    HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "errors": [
        {
            "message": "string"
        }
    ]
}
POST /environments/{envName}/applications

Creates a new Flink Application or updates an existing one in the given Environment.

Parameters:
  • envName (string) – Name of the Environment

Example request:

POST /environments/{envName}/applications HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "apiVersion": "string",
    "kind": "string",
    "metadata": {},
    "spec": {},
    "status": {}
}
Status Codes:
  • 201 Created –

    The Application was successfully created or updated.

    Example response:

    HTTP/1.1 201 Created
Content-Type: application/json

{
    "apiVersion": "string",
    "kind": "string",
    "metadata": {},
    "spec": {},
    "status": {}
}
  • 400 Bad Request –

    Bad request.

    Example response:

    HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "errors": [
        {
            "message": "string"
        }
    ]
}
  • 422 Unprocessable Entity –

    Request valid but invalid content.

    Example response:

    HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
    "errors": [
        {
            "message": "string"
        }
    ]
}
  • 500 Internal Server Error –

    Server error.

    Example response:

    HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "errors": [
        {
            "message": "string"
        }
    ]
}
GET /environments/{envName}/applications

Retrieve a paginated list of all applications in the given Environment.

Parameters:
  • envName (string) – Name of the Environment
Query Parameters:
 
  • page (integer) – Zero-based page index (0..N)
  • size (integer) – The size of the page to be returned
  • sort (array) – Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.

Example request:

GET /environments/{envName}/applications HTTP/1.1
Host: example.com
Status Codes:
  • 200 OK –

    Application found and returned.

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "pageable": {
        "page": 1,
        "size": 1,
        "sort": {
            "sorted": true,
            "unsorted": true,
            "empty": true
        }
    },
    "metadata": {
        "size": 1
    },
    "items": [
        {
            "apiVersion": "string",
            "kind": "string",
            "metadata": {},
            "spec": {},
            "status": {}
        }
    ]
}
  • 304 Not Modified – Not modified.
  • 500 Internal Server Error –

    Server error.

    Example response:

    HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "errors": [
        {
            "message": "string"
        }
    ]
}
Response Headers:
 
  • ETag – An ID for this version of the response.
GET /environments/{envName}/applications/{appName}

Retrieve an Application of the given name in the given Environment.

Parameters:
  • envName (string) – Name of the Environment
  • appName (string) – Name of the Application

Example request:

GET /environments/{envName}/applications/{appName} HTTP/1.1
Host: example.com
Status Codes:
  • 200 OK –

    Application found and returned.

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "apiVersion": "string",
    "kind": "string",
    "metadata": {},
    "spec": {},
    "status": {}
}
  • 304 Not Modified – Not modified.
  • 500 Internal Server Error –

    Server error.

    Example response:

    HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "errors": [
        {
            "message": "string"
        }
    ]
}
  • 404 Not Found –

    Application not found.

    Example response:

    HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "errors": [
        {
            "message": "string"
        }
    ]
}
Response Headers:
 
  • ETag – An ID for this version of the response.
DELETE /environments/{envName}/applications/{appName}

Deletes an Application of the given name in the given Environment.

Parameters:
  • envName (string) – Name of the Environment
  • appName (string) – Name of the Application
Status Codes:
  • 200 OK – Application found and deleted.
  • 304 Not Modified – Not modified.
  • 500 Internal Server Error –

    Server error.

    Example response:

    HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "errors": [
        {
            "message": "string"
        }
    ]
}
POST /environments/{envName}/applications/{appName}/start

Starts an earlier submitted Flink Application

Parameters:
  • envName (string) – Name of the Environment
  • appName (string) – Name of the Application
Status Codes:
  • 200 OK –

    Application started

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "apiVersion": "string",
    "kind": "string",
    "metadata": {},
    "spec": {},
    "status": {}
}
  • 304 Not Modified – Not modified.
  • 500 Internal Server Error –

    Server error.

    Example response:

    HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "errors": [
        {
            "message": "string"
        }
    ]
}
POST /environments/{envName}/applications/{appName}/suspend

Suspends an earlier started Flink Application

Parameters:
  • envName (string) – Name of the Environment
  • appName (string) – Name of the Application
Status Codes:
  • 200 OK –

    Application suspended

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "apiVersion": "string",
    "kind": "string",
    "metadata": {},
    "spec": {},
    "status": {}
}
  • 304 Not Modified – Not modified.
  • 500 Internal Server Error –

    Server error.

    Example response:

    HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "errors": [
        {
            "message": "string"
        }
    ]
}

Troubleshooting

  • Resource not found: If you encounter the error Resource not found… when making a GET call, it may be due to the wrong URL. Specifically, the requested REST resource might not exist.

    For example:

    • When making the GET call:

      GET http://localhost:8080/hello

      You will receive the error:

      Resource not found: [hello]

    • Similarly, if you make the GET call:

      GET http://localhost:8080/ or GET http://localhost:8080

      You will receive the error:

      Resource not found: []

      This occurs because you are requesting an empty resource.

Related content