Kayhan Space Screening API

openapi: 3.1.0
info:
  title: Satcat Service Authentication Screening API
  description: '

    Kayhan Space''s Satcat Service API.


    ## Features

    * **View** historical CDM data for an object.

    * **View** latest CDM data for an object.

    '
  contact:
    email: help@kayhan.space
  version: 1.0.0
servers:
- url: /api/satcat
tags:
- name: Screening
paths:
  /screenings/conjunction_plot:
    get:
      tags:
      - Screening
      summary: Get Conjunction Plot
      description: Get a summary of all the user's conjunctions.
      operationId: get_conjunction_plot_screenings_conjunction_plot_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ConjunctionMinimal'
                type: array
                title: Response Get Conjunction Plot Screenings Conjunction Plot Get
      security:
      - Oauth2Scheme: []
  /screenings:
    post:
      tags:
      - Screening
      summary: Create Screening
      description: "Create a screening.\n    Compares all points of the primary ephemerides which overlap in time with the\n    resolved assigned secondaries, and identify close-approaches which may require\n    the operator to perform collision avoidance action (conjunctions).\n    <br/>\n    Screenings are not automatically submitted for processing upon creation, unless the\n    `submit` query parameter is used. Screenings can be further configured using the\n    various `/screenings/{id}` endpoints and then submitted for processing using\n    `PUT /screenings/{id}/submit`.\n    <br/>\n    Because Screenings are processed in a queue, screening is an asynchronous operation.\n    The status and results of a submitted  screening can be found by retrieving\n    the Screening using `GET /screenings/{id}`."
      operationId: create_screening_screenings_post
      security:
      - Oauth2Scheme: []
      parameters:
      - name: submit
        in: query
        required: false
        schema:
          type: boolean
          description: Whether to automatically submit the screening for processing upon creation. If not used, the screening can be further configured and later submitted using the screening actions subresources.
          default: false
          title: Submit
        description: Whether to automatically submit the screening for processing upon creation. If not used, the screening can be further configured and later submitted using the screening actions subresources.
      - name: group_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Optional group ID to use for the request
          title: Group Id
        description: Optional group ID to use for the request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScreeningCreate'
              description: Configuration of the screening to create
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScreeningReadMinimal'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Screening
      summary: List Screenings
      description: List the screenings to which the currently authenticated user has read access.
      operationId: list_screenings_screenings_get
      security:
      - Oauth2Scheme: []
      parameters:
      - name: filters
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            contentMediaType: application/json
            contentSchema: {}
          - type: 'null'
          title: Filters
      - name: sort_field
        in: query
        required: false
        schema:
          type: string
          default: created_at
          title: Sort Field
      - name: sort_direction
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/SortDirection'
          default: desc
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      - name: count
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Count
      - name: fields
        in: query
        required: false
        schema:
          type: string
          title: Fields
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OffsetPageResult_ScreeningPreviewWithCoverage_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /screenings/{id}:
    get:
      tags:
      - Screening
      summary: Get Screening
      description: Retrieve metadata about a screening.
      operationId: get_screening_screenings__id__get
      security:
      - Oauth2Scheme: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      - name: fields
        in: query
        required: false
        schema:
          type: string
          title: Fields
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScreeningPreviewWithCoverage'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Screening
      summary: Update Screening
      description: Update the configuration of a screening. Can only be performed on Screenings that have not yet been submitted.
      operationId: update_screening_screenings__id__patch
      security:
      - Oauth2Scheme: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScreeningUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScreeningPreview'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Screening
      summary: Delete Screening
      description: Delete a screening. If the screening is running, causes the `cancel` operation to be taken on the screening, and the screening to be subsequently deleted. Any conjunctions associated with the screening are also deleted.
      operationId: delete_screening_screenings__id__delete
      security:
      - Oauth2Scheme: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /screenings/{id}/primaries:
    post:
      tags:
      - Screening
      summary: Add Screening Primary
      description: Add a Screenable to the list of primaries for a screening. If `norad_cat_id` is specified, must also be specified alongside `catalog_id`, and signifies that the ephemeris for object `norad_cat_id` from catalog `catalog_id` should be added.
      operationId: add_screening_primary_screenings__id__primaries_post
      security:
      - Oauth2Scheme: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScreenableCreate'
              description: Configuration of the primary to add
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScreeningPreview'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Screening
      summary: List Screening Primaries
      description: Get the list of primaries for a screening.
      operationId: list_screening_primaries_screenings__id__primaries_get
      security:
      - Oauth2Scheme: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      - name: filters
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            contentMediaType: application/json
            contentSchema: {}
          - type: 'null'
          title: Filters
      - name: sort_field
        in: query
        required: false
        schema:
          type: string
          default: created_at
          title: Sort Field
      - name: sort_direction
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/SortDirection'
          default: desc
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      - name: count
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Count
      - name: fields
        in: query
        required: false
        schema:
          type: string
          title: Fields
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OffsetPageResult_PrimaryReadWithCoverage_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /screenings/{id}/secondaries:
    post:
      tags:
      - Screening
      summary: Add Screening Secondary
      description: Add a Screenable to the list of secondaries for a screening. If `norad_cat_id` is specified, must also be specified alongside `catalog_id`, and signifies that the ephemeris for object `norad_cat_id` from catalog `catalog_id` should be added. If `catalog_id` is specified alone, signifies that the whole catalog should be used.
      operationId: add_screening_secondary_screenings__id__secondaries_post
      security:
      - Oauth2Scheme: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScreenableCreate'
              description: Configuration of the secondary to add
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScreeningRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Screening
      summary: List Screening Secondaries
      description: Get the list of primaries for a screening.
      operationId: list_screening_secondaries_screenings__id__secondaries_get
      security:
      - Oauth2Scheme: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      - name: filters
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            contentMediaType: application/json
            contentSchema: {}
          - type: 'null'
          title: Filters
      - name: sort_field
        in: query
        required: false
        schema:
          type: string
          default: created_at
          title: Sort Field
      - name: sort_direction
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/SortDirection'
          default: desc
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      - name: count
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Count
      - name: fields
        in: query
        required: false
        schema:
          type: string
          title: Fields
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OffsetPageResult_SecondaryReadWithCoverage_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /screenings/{id}/screenables_batch:
    post:
      tags:
      - Screening
      summary: Add Screenables Batch
      operationId: add_screenables_batch_screenings__id__screenables_batch_post
      security:
      - Oauth2Scheme: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Body_add_screenables_batch_screenings__id__screenables_batch_post'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScreeningPreview'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Screening
      summary: Remove Screening Screenables Batch
      description: Remove a set of Screenables from a screening.
      operationId: remove_screening_screenables_batch_screenings__id__screenables_batch_delete
      security:
      - Oauth2Scheme: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: ID of the screening to modify
          title: Id
        description: ID of the screening to modify
      - name: primary_id
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
              format: uuid
          - type: 'null'
          description: IDs of the primaries to remove from the screening. Specify the query parameter multiple times to delete multiple primaries.
          title: Primary Id
        description: IDs of the primaries to remove from the screening. Specify the query parameter multiple times to delete multiple primaries.
      - name: secondary_id
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
              format: uuid
          - type: 'null'
          description: IDs of the secondaries to remove from the screening. Specify the query parameter multiple times to delete multiple secondaries.
          title: Secondary Id
        description: IDs of the secondaries to remove from the screening. Specify the query parameter multiple times to delete multiple secondaries.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScreeningRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /screenings/{id}/primaries/{primary_id}:
    delete:
      tags:
      - Screening
      summary: Remove Screening Primary
      description: Remove a Screenable from the list of primaries for a screening.
      operationId: remove_screening_primary_screenings__id__primaries__primary_id__delete
      security:
      - Oauth2Scheme: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: ID of the screening to modify
          title: Id
        description: ID of the screening to modify
      - name: primary_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: ID of the primary to remove from the screening
          title: Primary Id
        description: ID of the primary to remove from the screening
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScreeningRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /screenings/{id}/secondaries/{secondary_id}:
    delete:
      tags:
      - Screening
      summary: Remove Screening Secondary
      description: Remove a Screenable from the list of secondaries for a screening.
      operationId: remove_screening_secondary_screenings__id__secondaries__secondary_id__delete
      security:
      - Oauth2Scheme: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: ID of the screening to modify
          title: Id
        description: ID of the screening to modify
      - name: secondary_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: ID of the secondary to remove from the screening
          title: Secondary Id
        description: ID of the secondary to remove from the screening
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScreeningRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /screenings/{id}/submit:
    put:
      tags:
      - Screening
      summary: Submit Screening
      description: Submit a screening for processing. Submitting a screening is an idempotent operation. Once a screening has been submitted and entered the PENDING state, submitting it again will have no further effect. <br/> If the screening as configured at submission fails validation, the server will return HTTP status 422 (Unprocessable Entity) and the screening will not enter the PENDING state until the configuration is updated and the screening is submitted again.
      operationId: submit_screening_screenings__id__submit_put
      security:
      - Oauth2Scheme: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScreeningRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /screenings/{id}/cancel:
    put:
      tags:
      - Screening
      summary: Cancel Screening
      description: Cancel a screening which has the status RUNNING, causing the screening operation to be abandoned and the job to enter the CANCELED status.
      operationId: cancel_screening_screenings__id__cancel_put
      security:
      - Oauth2Scheme: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScreeningRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /screenings/{id}/archive:
    put:
      tags:
      - Screening
      summary: Archive Screening
      description: Mark a screening as archived.
      operationId: archive_screening_screenings__id__archive_put
      security:
      - Oauth2Scheme: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScreeningRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /screenings/{id}/conjunctions:
    get:
      tags:
      - Screening
      summary: List Screening Conjunctions
      description: List the conjunctions which the screening generated.
      operationId: list_screening_conjunctions_screenings__id__conjunctions_get
      security:
      - Oauth2Scheme: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      - name: filters
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            contentMediaType: application/json
            contentSchema: {}
          - type: 'null'
          title: Filters
      - name: sort_field
        in: query
        required: false
        schema:
          type: string
          default: created_at
          title: Sort Field
      - name: sort_direction
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/SortDirection'
          default: desc
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      - name: count
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Count
      - name: fields
        in: query
        required: false
        schema:
          type: string
          title: Fields
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OffsetPageResult_ConjunctionRead_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /screenings/{id}/conjunctions/{conjunction_id}:
    get:
      tags:
      - Screening
      summary: Get Screening Conjunction
      description: Retrieve metadata about a single screening conjunction.
      operationId: get_screening_conjunction_screenings__id__conjunctions__conjunction_id__get
      security:
      - Oauth2Scheme: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      - name: conjunction_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Conjunction Id
      - name: fields
        in: query
        required: false
        schema:
          type: string
          title: Fields
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConjunctionRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /screenings/{id}/catalogs/{catalog_id}/ephemerides:
    get:
      tags:
      - Screening
      summary: List Ephemerides In Catalog By Screening
      description: List the ephemerides available in the catalog and their relationship to the screening, if any.
      operationId: list_ephemerides_in_catalog_by_screening_screenings__id__catalogs__catalog_id__ephemerides_get
      security:
      - Oauth2Scheme: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      - name: catalog_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Catalog Id
      - name: filters
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            contentMediaType: application/json
            contentSchema: {}
          - type: 'null'
          title: Filters
      - name: sort_field
        in: query
        required: false
        schema:
          type: string
          default: created_at
          title: Sort Field
      - name: sort_direction
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/SortDirection'
          default: desc
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      - name: count
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Count
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OffsetPageResult_EphemerisMetadataScreeningRead_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /screenings/{id}/catalogs/{catalog_id}:
    get:
      tags:
      - Screening
      summary: Get Catalog By Screening
      description: Get the catalog and its ephemerides' relationships to the screening, if any.
      operationId: get_catalog_by_screening_screenings__id__catalogs__catalog_id__get
      security:
      - Oauth2Scheme: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      - name: catalog_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Catalog Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogScreeningPreviewRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /screenings/{id}/catalogs:
    get:
      tags:
      - Screening
      summary: List Catalogs By Screening
      description: List the available in the catalog and their ephemerides' relationships to the screening, if any. If using the `latest` parameter, return only the latest catalog available for each individual catalog type available. Pagination parameters are ignored when using the `latest` parameter. Additionally, archived and unready catalogs are not returned when using the `latest` parameter.
      operationId: list_catalogs_by_screening_screenings__id__catalogs_get
      security:
      - Oauth2Scheme: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      - name: latest
        in: query
        required: false
        schema:
          type: boolean
          description: Whether to retrieve only the latest catalog for each applicable catalog_type.
          default: false
          title: Latest
        description: Whether to retrieve only the latest catalog for each applicable catalog_type.
      - name: filters
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            contentMediaType: application/json
            contentSchema: {}
          - type: 'null'
          title: Filters
      - name: sort_field
        in: query
        required: false
        schema:
          type: string
          default: created_at
          title: Sort Field
      - name: sort_direction
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/SortDirection'
          default: desc
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      - name: count
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Count
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OffsetPageResult_CatalogScreeningPreviewRead_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /screenings/{id}/results/ccsds:
    get:
      tags:
      - Screening
      summary: Get Screening Results Ccsds List
      description: Retrieve screening conjunction results as a list of serialized JSON objects in CCSDS format.
      operationId: get_screening_results_ccsds_list_screenings__id__results_ccsds_get
      security:
      - Oauth2Scheme: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: ID of the screening to get results for
          title: Id
        description: ID of the screening to get results for
      - name: filters
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            contentMediaType: application/json
            contentSchema: {}
          - type: 'null'
          title: Filters
      - name: sort_field
        in: query
        required: false
        schema:
          type: string
          default: created_at
          title: Sort Field
      - name: sort_direction
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/SortDirecti

# --- truncated at 32 KB (128 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kayhan-space/refs/heads/main/openapi/kayhan-space-screening-api-openapi.yml