openapi: 3.2.0
info:
  description: A description of the ReferenceService API. in progress
  title: Generative AI Service NL2SQL Generate Sql From Nl Job API
  version: '20260325'
  x-provenance:
    method: harvested
    first_party: true
    publisher: Oracle
    source: https://docs.oracle.com/en-us/iaas/api/specs/2292d191d8e507557733c33ec3b7902d15322d28c171d878ef5fb0bce8ef272e.yaml
    harvested: '2026-08-04'
    note: Published by Oracle as the contract for the Generative AI Service NL2SQL API OCI service and stored verbatim; API Evangelist added only this provenance block.
  x-evidence:
  - url: https://docs.oracle.com/en-us/iaas/api/specs/index.json
    what: Oracle's own index of every OCI service specification
  - url: https://docs.oracle.com/en-us/iaas/api/specs/2292d191d8e507557733c33ec3b7902d15322d28c171d878ef5fb0bce8ef272e.yaml
    what: the harvested document for Generative AI Service NL2SQL API
servers:
- url: http://127.0.0.1/20260325
- url: https://127.0.0.1/20260325
tags:
- name: generateSqlFromNlJob
paths:
  /semanticStores/{semanticStoreId}/actions/generateSqlFromNl:
    post:
      description: 'Generates a SQL query from a natural language input for the specified SemanticStore.

        '
      operationId: GenerateSqlFromNl
      parameters:
      - $ref: '#/components/parameters/RetryTokenHeader'
      - $ref: '#/components/parameters/RequestIdHeader'
      - $ref: '#/components/parameters/IfMatchHeader'
      - $ref: '#/components/parameters/semanticStoreIdPathParam'
      responses:
        201:
          description: The GenerateSqlFromNlJob is created successfully.
          headers:
            etag:
              description: 'For optimistic concurrency control. See `if-match`.

                '
              schema:
                type: string
            opc-request-id:
              description: 'Unique Oracle-assigned identifier for the request. If you need to contact

                Oracle about a particular request, please provide the request ID.

                '
              schema:
                type: string
            opc-work-request-id:
              description: 'Unique Oracle-assigned identifier for the asynchronous work. You can use this to query its status.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateSqlFromNlJob'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        409:
          $ref: '#/components/responses/409'
        412:
          $ref: '#/components/responses/412'
        429:
          $ref: '#/components/responses/429'
        500:
          $ref: '#/components/responses/500'
        default:
          $ref: '#/components/responses/default'
      summary: Generate SQL from natural language for a SemanticStore
      tags:
      - generateSqlFromNlJob
      x-related-resource: '#/definitions/GenerateSqlFromNlJob'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateSqlFromNlDetails'
        description: Details for generating SQL from natural language.
        required: true
components:
  parameters:
    IfMatchHeader:
      description: 'For optimistic concurrency control. In the PUT or DELETE call

        for a resource, set the `if-match` parameter to the value of the

        etag from a previous GET or POST response for that resource.

        The resource will be updated or deleted only if the etag you

        provide matches the resource''s current etag value.

        '
      in: header
      name: if-match
      required: false
      schema:
        type: string
    RequestIdHeader:
      description: The client request ID for tracing.
      in: header
      name: opc-request-id
      schema:
        type: string
    RetryTokenHeader:
      description: 'A token that uniquely identifies a request so it can be retried in case of a timeout or

        server error without risk of executing that same action again. Retry tokens expire after 24

        hours, but can be invalidated before then due to conflicting operations. For example, if a resource

        has been deleted and purged from the system, then a retry of the original creation request

        might be rejected.

        '
      in: header
      name: opc-retry-token
      required: false
      schema:
        type: string
        maxLength: 64
        minLength: 1
    semanticStoreIdPathParam:
      description: The OCID of the semantic store
      in: path
      name: semanticStoreId
      required: true
      schema:
        type: string
  schemas:
    GenerateSqlFromNlJob:
      description: 'Object representing to GenerateSqlFromNlJob.

        ocidEntityType: generativeaiGenerateSqlFromNlJob

        adLocality: regional

        '
      properties:
        definedTags:
          additionalProperties:
            additionalProperties:
              type: object
            type: object
          description: 'Defined tags for this resource. Each key is predefined and scoped to a namespace.

            Example: `{"foo-namespace": {"bar-key": "value"}}`

            '
          type: object
        description:
          description: An optional description of the GenerateSqlFromNlJob.
          maxLength: 400
          minLength: 1
          type: string
          x-default-description: 'null'
        displayName:
          description: A user-friendly display name. It does not have to be unique and can be modified. Avoid entering confidential information.
          maxLength: 255
          minLength: 1
          type: string
        freeformTags:
          additionalProperties:
            type: string
          description: 'Simple key-value pair that is applied without any predefined name, type or scope. Exists for cross-compatibility only.

            Example: `{"bar-key": "value"}`

            '
          type: object
        id:
          description: Unique identifier that is immutable on creation.
          type: string
        inputNaturalLanguageQuery:
          description: "A user-provided query or instruction written in plain, conversational language. \nThis input is intended to capture the user's intent, question, or command without requiring technical syntax or structured formatting. \nThe query should clearly express what the user wants to know or accomplish, allowing the system to interpret and respond appropriately.\n"
          maxLength: 4096
          minLength: 1
          type: string
        jobOutput:
          $ref: '#/components/schemas/JobOutput'
        lifecycleDetails:
          description: A message describing the current state in more detail that can provide actionable information.
          type: string
        lifecycleState:
          description: The lifecycleState of GenerateSqlFromNlJob.
          enum:
          - ACCEPTED
          - IN_PROGRESS
          - FAILED
          - SUCCEEDED
          - CANCELING
          - CANCELED
          type: string
          x-obmcs-top-level-enum: '#/definitions/LifecycleState'
        semanticStoreId:
          description: Owning SemanticStore [OCID](/iaas/Content/General/Concepts/identifiers.htm) for a GenerateSqlFromNlJob.
          maxLength: 255
          minLength: 1
          type: string
        systemTags:
          additionalProperties:
            additionalProperties:
              type: object
            type: object
          description: 'System tags for this resource. Each key is predefined and scoped to a namespace.

            Example: `{"orcl-cloud": {"free-tier-retained": "true"}}`

            '
          type: object
        timeAccepted:
          description: The date and time that the enrichment job was accepted in the format of an RFC3339 datetime string.
          format: date-time
          type: string
        timeFinished:
          description: The date and time that the enrichment job was finished in the format of an RFC3339 datetime string.
          format: date-time
          type: string
        timeStarted:
          description: The date and time that the enrichment job was started in the format of an RFC3339 datetime string.
          format: date-time
          type: string
      required:
      - id
      - semanticStoreId
      - timeAccepted
      - lifecycleState
      - lifecycleDetails
      type: object
    GenerateSqlFromNlDetails:
      description: The data to create a GenerateSqlFromNlJob.
      properties:
        definedTags:
          additionalProperties:
            additionalProperties:
              type: object
            type: object
          description: 'Defined tags for this resource. Each key is predefined and scoped to a namespace.

            Example: `{"foo-namespace": {"bar-key": "value"}}`

            '
          type: object
        description:
          description: An optional description of the GenerateSqlFromNlJob.
          maxLength: 400
          minLength: 1
          type: string
          x-default-description: 'null'
        displayName:
          description: A user-friendly display name. It does not have to be unique and can be modified. Avoid entering confidential information.
          maxLength: 255
          minLength: 1
          type: string
        freeformTags:
          additionalProperties:
            type: string
          description: 'Simple key-value pair that is applied without any predefined name, type or scope. Exists for cross-compatibility only.

            Example: `{"bar-key": "value"}`

            '
          type: object
        inputNaturalLanguageQuery:
          description: "A user-provided query or instruction written in plain, conversational language. \nThis input is intended to capture the user's intent, question, or command without requiring technical syntax or structured formatting. \nThe query should clearly express what the user wants to know or accomplish, allowing the system to interpret and respond appropriately.\n"
          maxLength: 4096
          minLength: 1
          type: string
      required:
      - inputNaturalLanguageQuery
      type: object
    Error:
      description: Error Information.
      properties:
        code:
          description: A short error code that defines the error, meant for programmatic parsing.
          type: string
        message:
          description: A human-readable error string.
          type: string
      required:
      - code
      - message
    JobOutput:
      description: 'A JobOutput delivers content generated by the GenerateSQLJob to a given location, which corresponds with type-specific characteristics.

        '
      discriminator:
        propertyName: jobOutputLocation
      properties:
        jobOutputLocation:
          description: Discriminator indicating where the job output is delivered. Currently only INLINE is supported.
          enum:
          - INLINE
          type: string
          x-obmcs-top-level-enum: '#/definitions/JobOutputLocation'
      required:
      - jobOutputLocation
  responses:
    default:
      description: Unknown Error
      headers:
        opc-request-id:
          description: 'Unique Oracle-assigned identifier for the request. If you need to contact

            Oracle about a particular request, please provide the request ID.

            '
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
x-anchors:
  x-headers:
    etag:
      description: 'For optimistic concurrency control. See `if-match`.

        '
      type: string
    opc-next-page:
      description: 'For pagination of a list of items. When paging through a list, if this header appears in the response,

        then a partial list might have been returned. Include this value as the `page` parameter for the

        subsequent GET request to get the next batch of items.

        '
      type: string
    opc-prev-page:
      description: 'For list pagination. When this header appears in the response, previous pages of results remain. For

        important details about how pagination works, see [List Pagination](/iaas/Content/API/Concepts/usingapi.htm#nine).

        '
      type: string
    opc-request-id:
      description: 'Unique Oracle-assigned identifier for the request. If you need to contact

        Oracle about a particular request, please provide the request ID.

        '
      type: string
    opc-work-request-id:
      description: 'Unique Oracle-assigned identifier for the asynchronous work. You can use this to query its status.

        '
      type: string
  x-properties:
    definedTags:
      additionalProperties:
        additionalProperties:
          type: object
        type: object
      description: 'Defined tags for this resource. Each key is predefined and scoped to a namespace.

        Example: `{"foo-namespace": {"bar-key": "value"}}`

        '
      type: object
    freeformTags:
      additionalProperties:
        type: string
      description: 'Simple key-value pair that is applied without any predefined name, type or scope. Exists for cross-compatibility only.

        Example: `{"bar-key": "value"}`

        '
      type: object
    systemTags:
      additionalProperties:
        additionalProperties:
          type: object
        type: object
      description: 'System tags for this resource. Each key is predefined and scoped to a namespace.

        Example: `{"orcl-cloud": {"free-tier-retained": "true"}}`

        '
      type: object
x-obmcs-client-retries-enabled: true
x-oracle-package: com.oracle.oci.sfw