bver/both.yaml

## both.yaml
### GENERATED FILE. DO NOT EDIT THIS FILE, EDIT src/*.m4.yaml FILES INSTEAD ###

swagger: '2.0'

info:
  title: Ytica API
  description: |
    Ytica API consists of two services: Identity and Speech Analytics.

    Currently, Speech Analytics Services provides basic recording statistics and phrase spotting for a single audio recording.
  version: draft

schemes:
  - https

x-tagGroups:
  - name: Identity Service
    tags:
      - Authorization Token
  - name: Speech Analytics Service
    tags:
      - Speech Jobs
      - Job Results

securityDefinitions:
  Bearer:
    type: apiKey
    name: Authorization
    in: header
    description: |
       For accessing the API a valid JWT token must be passed in the 'Authorization' header.
       A JWT token is generated by the Identity Service and is valid for a limited time period.
       The following syntax must be used in the 'Authorization' header :

              Bearer: xxxxxx.yyyyyyy.zzzzzz

       where xxxxxx.yyyyyyy.zzzzzz is the issued JWT token
    x-example: 'Bearer: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ'

paths:

# {{ m4 preprocessor

  "/identity/authorizations":
    x-summary: Authorizing Identity Service
    x-description: |
      Endpoint for user authorizations.

    post:
      tags:
        - Authorization Token
      summary: Provides the new authorization token for the use in all Ytica API services.
      description: |
        This operation authorizes the API user for all Ytica API services.

        The API secret token was given to the user to authenticate her for API operations. It's main purpose is to
        establish the user's identity in the context of Ytica API services.
        The API secret token has not restricted validity so the user is responsible for keeping it safe and must
        guarantee it cannot leak outside user's application.

        For performance and security reasons the API secret token cannot be used directly for accessing executive API
        operations. Instead, the user has to ask for authorization first using this POST.
        The authorization process simply takes the API secret token and generates the authorization token with
        the time-restricted validity. This authorization token is self-contained and (currently) respects RFC 7519
        standard.

        It can be repeatedly used in executive API operations untill it expires. The expiration time can be parsed from
        the token however for the user convenience it is returned in the response in a human readable form of ISO 8601
        Extended Format. The user should ask for another authorization token sufficiently in advance.

        Each call of this operation generates a new authorization token with a new expiration time so it is possible to
        get a new one soon after its generation. However too frequent regeneration leads to performance loses and is
        discouraged.
        The best practice is to respect the expiration time and schedule re-generation according it, obviously with
        some time buffer covering the call latence. Asking for a new authorization token right before each executive
        API operation is an antipattern.

      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        -
          name: body
          in: body
          description: JSON containing the API secret token
          required: true
          schema:
            $ref: '#/definitions/AuthorizationRequest'
      responses:
        200:
          description: Generates the authorization token with the time restriction.
          headers:
            Content-type:
              type: string
              description: application/json
          schema:
            $ref: '#/definitions/AuthorizationResponse'
        400:
          description: Unexpected error
          headers:
             Content-type:
               type: string
               description: application/problem+json
          schema:
            $ref: '#/definitions/ProblemDetail'
        403:
          description: Authorization error
          headers:
             Content-type:
              type: string
              description: application/problem+json
          schema:
            $ref: '#/definitions/ProblemDetailAuth'

  "/speech/jobs":
    x-summary: Speech Analytic Jobs
    x-description: |
      All speech analytics jobs are asynchronous since the time between http request and response is often not
      sufficient for the job to be completed. Therefore task definitions are accepted by a single API call and results are sent back to the user defined callback when ready.
    post:
      tags:
        - Speech Jobs

      summary: Create a new composite analytic job
      description: |
        Starts an analytic job as a composite request consisting of several tasks:
        - Statistics (optional)
        - Search for Phrases (optional)
        - Transcripts (in the future)

        At least one _task_ has to be specified.

        ### Statistics

        Basic statistics are:
        - Total length of the audio
        - Cummulative cross-talk time
        - Mutual silence time
        - Talk times per channel

        All stats are reported in seconds.

        Stats are computed when

            statistics: {}

        key is present in the _tasks_ attribute.

        ### Phrases

        This _embedded resource _phrase_set_ defines a set or list of text phrases in a specific
        language we want to look for.

        The _min_confidence_ parameter specifies the minimal confidence enabling to set the confidence
        threshold. Phrase findings with the confidence lower than the confidence thresholds are not
        reported which helps to reduce the number of false alarms at the speech engine level.

        There are two ways how to specify the phrase set:
        - Phrase List .. simple array of all phrases
        - Phrases Object .. with the minimal confidence specified for each phrase.

        ### Recording

        There is a link in the job definition which specifies the audio URL.
        The audio URL must be accessible to the Speech Service. It might contain an opaque hash as
        a mean of a basic trust between consumer and the Speech Service.

        Recording represents the way the Speech API knows audio data.
        The supported audio format is:

                8kHz stereo WAV (both 16bit PCM and A-law)

        We may support different formats and different transport strategies in the future.
        Mono WAVs are also tolerated, however one channel per speaker condition is required i.e. mixing
        speakers in mono channels is not allowed. A single recording can store a conversation consisting
        one or more channels. Typically, the Recording is the stereo WAV where two speakers talk to each
        other, each speaker has a separate channel. However, a single recording (a single conversation)
        can be recorded in more WAVs with different offsets for channels. The only requirement is that
        a speech of more speakers must not mix in a single channel.

        #### Result Callback

        The client has to provide _links with the results_callback.
        Again, the URL can be opaque as in the case of recording audio.

        Please note that there are no exact guarantees w.r.t. the time between the job creation and
        sending back results.
      security:
        - Bearer: []
      consumes:
        - application/hal+json
      produces:
        - application/hal+json
      parameters:
        -
          name: body
          in: body
          description: HAL (JSON) describing the analytic job.
          required: true
          schema:
            $ref: '#/definitions/JobDescription'
      responses:
        202:
          description: Accepted the new asynchronous job
          headers:
            Content-type:
              type: string
              description: application/hal+json
          schema:
            $ref: '#/definitions/JobAccepted'
        400:
          description: Unexpected error
          headers:
             Content-type:
               type: string
               description: application/problem+json
          schema:
            $ref: '#/definitions/ProblemDetail'
        403:
          description: Authorization error
          headers:
             Content-type:
              type: string
              description: application/problem+json
          schema:
            $ref: '#/definitions/ProblemDetailAuth'

  "/any/path/to/consumer/provided/endpoint":
    x-summary: Callback Receiving Endpoint
    x-description: |
      The client's endpoint is called with the URL provided by _links with the results_callback specified
      by Job Creation operation.

    post:
      tags:
        - Job Results

      summary: Receive results
      description: |
        Inform Ytica API consumer about the results of asynchronous job by calling the endpoint.
        The endpoint URL must be accessible to the Speech Service and defined in _links section of
        the Job Creation operation.

        The client is informed about the job outcome (completed/failed).

        All specified tasks have their according tasks_result.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        -
          name: body
          in: body
          description: JSON describing the result.
          required: true
          schema:
            $ref: '#/definitions/CallbackRequest'
      responses:
        200:
          description: Consumer informs the Speech Service that succesfuly received results.
          headers:
            Content-type:
              type: string
              description: application/hal+json
          schema:
            $ref: '#/definitions/CallbackResponse'
        400:
          description: Unexpected error
          headers:
             Content-type:
              type: string
              description: application/problem+json
          schema:
            $ref: '#/definitions/ProblemDetail'


# }} m4 preprocessor

definitions:

# {{ m4 preprocessor

  AuthorizationRequest:
    title: The API secret token authenticating the user
    description: |
      The secret information proving the user's identity in the context of Ytica API services.
    type: object
    properties:
      api_secret_token:
        type: string
        description: Authentication API Secret Token which proves the API consumer identity.
    required:
      - api_secret_token
    example:
      api_secret_token: '89281f03-7e0e-4e50-b06f-e1e5393aef76'

  AuthorizationResponse:
    title: The authorization of the user
    description: |
      Authorization token and expiration information.
    properties:
      authorization_token:
        type: string
        description: The self-contained authorization token.
      expire:
        type: string
        description: Token expiration time respecting ISO 8601.
    required:
      - authorization_token
      - expire
    example:
      authorization_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ'
      expire: '2017-05-09T11:00:55.712Z'


  JobDescription:
    title: The composite speech analytic job.
    description: |
      The resource representing the asynchronous speech analytic job consisting of several tasks.
      Any task binds a recording with any of:
      - simple statistics
      - phrase search
      - transcripts (in the future).
      Results are available via results_callback.
    type: object
    properties:
      _links:
        type: object
        properties:
          results_callback:
            description: |
              Callback is triigerred by the Speech service when job results are ready.
              In the rare case of a failed job the callback is called with the content-type problem+json.
            type: object
            properties:
              href:
                type: string
                format: url
            required:
              - href
          recording_audio:
            description: The accessible location of the audio recording.
            type: object
            properties:
              href:
                type: string
                format: url
            required:
              - href
        required:
          - results_callback
          - recording_audio
      _embedded:
        type: object
        properties:
          phrase_set:
            $ref: '#/definitions/PhraseSet'
      tasks:
        type: object
        description: |
          Tasks parameters define parts of the job. If the key is omitted the task will not be processed.
          At least one of
            - statistics
            - phrase_spotting
          must be present.
        properties:
          statistics:
            type: object
            description: Ask for simple recording statistics to be computed.
          phrase_spotting:
            type: object
            description: If the phrase_spotting task is specified the  _embedded must contain the phrase_set.
            properties:
              min_confidence:
                type: number
                format: float
                minimum: 20.0
                description: Minimum confidence threshold allowing filtration (default for all phrases in PhraseSet).
#       anyOf:
#         - statistics
#         - phrase_spotting
    required:
      - _links
      - tasks
    example:
      _links:
        results_callback:
          href: 'http://example.com/results_endpoint/4354235_34_3255'
        recording_audio:
          href: 'http://example.com/external_storage/42/recordings/4354235_34.wav'
      _embedded:
        phrase_set:
          phrase_list:
            - hello
            - how are you
          language: en-US
      tasks:
        statistics: {}
        phrase_spotting:
          min_confidence: 30.0

  PhraseSet:
    title: Phrase Set
    description: |
      This is the set of phrases to be searched in audio files.
      There are two ways of defining phrases: Using
      - phrase_list .. a simple array of phrase texts
      - phrases .. an array of phrase objects for an individual control of the minimal confidence threshold.
    type: object
    properties:
      phrase_list:
        type: array
        items:
          type: string
        description: Phrase texts
      phrases:
        type: array
        items:
          type: object
          properties:
            text:
              type: string
              description: Phrase text
            min_confidence:
              type: number
              format: float
              minimum: 20.0
              description: Minimal confidence threshold for a particular phrase
          required:
            - text
      language:
        type: string
        description: |
          Language of the Phrase set (e.g. en-US).
          See https://tools.ietf.org/html/rfc5646 or http://www.lingoes.net/en/translator/langcode.htm
    required:
      - language
#   anyOf:
#     - phrase_list
#     - phrases
    example:
      phrase_list:
        - hello
        - how are you
      language: en-US


  ResultsStatistics:
    title: Results of the statistics task
    description: Simple cummulative information about speech/silence parts th the recording in audio channels.
    type: object
    properties:
      total_length:
        type: number
        format: float
        description: Total duration of the call (in seconds)
      cross_talk:
        type: number
        format: float
        description: Total duration of crosstalks (in seconds)
      cross_silence:
        type: number
        format: float
        description: Total duration of silence in all channels (in seconds)
      talk_times:
        type: array
        items:
          type: number
          format: float
        description: |
          Cummulative duration of talk parts per channel (in seconds)
          Each array value coresponds with the audio channel.
    example:
      total_length: 480.1
      cross_silence: 201.34
      cross_talk: 11.2
      talk_times:
        - 87.45
        - 145.32

  ResultsPhrases:
    title: Result of the phrase search.
    description: Phrases found in the recording.
    type: object
    properties:
      phrases_found:
        type: array
        items:
          type: object
          description: 'Single phrase searched'
          properties:
            text:
              type: string
              description: 'A phrase text (echo from Phrases model)'
            findings:
              description: 'All occurrences found in the recording'
              type: array
              items:
                type: object
                properties:
                  channel:
                    type: integer
                    description: 'Channel index (e.g. 0 or 1 for a stereo audio file)'
                  from:
                    type: number
                    format: float
                    description: 'Beginning of the phrase occurrence (in secs)'
                  to:
                    type: number
                    format: float
                    description: 'End of the phrase occurrence (in secs)'
                  confidence:
                    type: number
                    format: float
                    description: 'Phrase was found with this confidence'
      language:
        type: string
        description: |
          Language of the Phrase set (e.g. en-US).
          See https://tools.ietf.org/html/rfc5646 or http://www.lingoes.net/en/translator/langcode.htm

    example:
      language: en-US
      phrases_found:
        -
          text: hello
          findings:
            -
              channel: 0
              from: 5.33
              to: 5.98
              confidence: 47.74
            -
              channel: 1
              from: 2.13
              to: 3.58
              confidence: 87.14
        -
          text: can i help ya
        -
          text: well not exactly
        -
          text: how are you
          findings:
            -
              channel: 1
              from: 4.13
              to: 3.76
              confidence: 77.14

  CallbackResponse:
    title: Succesful Callback Response
    description: An empty response required
    type: object
    additionalProperties: false

  CallbackRequest:
    title: Asynchronous analytic job response
    description: |
        Asynchronous speech analytic results:
                       - simple statistics
                       - phrase search
                       - transcripts (in the future).
    type: object
    properties:
      _links:
        type: object
        properties:
          recording_audio:
            description: The accessible location of the audio recording.
            type: object
            properties:
              href:
                type: string
                format: url
            required:
              - href
        required:
          - recording_audio
      outcome:
        type: string
        enum:
          - completed
          - failed
      tasks_result:
        type: object
        properties:
          statistics:
            $ref: '#/definitions/ResultsStatistics'
          phrase_spotting:
            $ref: '#/definitions/ResultsPhrases'
    required:
      - _links
      - outcome
    example:
      _embedded:
        recording:
          _links:
            audio:
              href: 'http://example.com/external_storage/42/recordings/4354235_34.wav'
      outcome: completed
      tasks_result:
        statistics:
          total_length: 480.1
          cross_silence: 201.34
          cross_talk: 11.2
          talk_times:
            - 87.45
            - 145.32
        phrase_spotting:
          language: en-US
          phrases_found:
            -
              text: hello
              findings:
                -
                  channel: 0
                  from: 5.33
                  to: 5.98
                  confidence: 47.74
                -
                  channel: 1
                  from: 2.13
                  to: 3.58
                  confidence: 87.14
            -
              text: can i help ya
            -
              text: well not exactly
            -
              text: how are you
              findings:
                -
                  channel: 1
                  from: 4.13
                  to: 3.76
                  confidence: 77.14


  JobAccepted:
    title: The analytics job was accepted.
    description: |
      This is the information for the customer that the asynchronous job description was received.
      Related resources (audio and phrases) are also referenced here.
    type: object
    properties:
      status:
        type: string
        enum:
          - queued
        description: The status of the job. Currently, only 'queued' is supported.
    required:
      - status
    example:
      status: queued


#  shared in definitions:

  ProblemDetail:
    title: Normalized response in the case of problems.
    description: 'Please see https://tools.ietf.org/html/rfc7807'
    type: object
    properties:
      type:
        type: string
        format: url
      title:
        type: string
      status:
        type: number
      detail:
        type: string
    required:
      - title
      - detail
    example:
      type: https://developers.ytica.com/api/problems/bad-params
      title: Bad parameters
      detail: The required parameter missing.
      status: 400

  ProblemDetailAuth:
    title: Example response in the case of auth issues
    description: 'Please see https://tools.ietf.org/html/rfc7807'
    type: object
    properties:
      type:
        type: string
        format: url
      title:
        type: string
      status:
        type: number
      detail:
        type: string
    required:
      - title
      - detail
    example:
      type: https://developers.ytica.com/api/problems/auth-failed
      title: Authorization failed
      detail: Insufficient parmissions in the auth token.
      status: 403
# }} m4 preprocessor
	### GENERATED FILE. DO NOT EDIT THIS FILE, EDIT src/*.m4.yaml FILES INSTEAD ###

	swagger: '2.0'

	info:
	title: Ytica API
	description: \|
	Ytica API consists of two services: Identity and Speech Analytics.

	Currently, Speech Analytics Services provides basic recording statistics and phrase spotting for a single audio recording.
	version: draft

	schemes:
	- https

	x-tagGroups:
	- name: Identity Service
	tags:
	- Authorization Token
	- name: Speech Analytics Service
	tags:
	- Speech Jobs
	- Job Results

	securityDefinitions:
	Bearer:
	type: apiKey
	name: Authorization
	in: header
	description: \|
	For accessing the API a valid JWT token must be passed in the 'Authorization' header.
	A JWT token is generated by the Identity Service and is valid for a limited time period.
	The following syntax must be used in the 'Authorization' header :

	Bearer: xxxxxx.yyyyyyy.zzzzzz

	where xxxxxx.yyyyyyy.zzzzzz is the issued JWT token
	x-example: 'Bearer: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ'

	paths:

	# {{ m4 preprocessor

	"/identity/authorizations":
	x-summary: Authorizing Identity Service
	x-description: \|
	Endpoint for user authorizations.

	post:
	tags:
	- Authorization Token
	summary: Provides the new authorization token for the use in all Ytica API services.
	description: \|
	This operation authorizes the API user for all Ytica API services.

	The API secret token was given to the user to authenticate her for API operations. It's main purpose is to
	establish the user's identity in the context of Ytica API services.
	The API secret token has not restricted validity so the user is responsible for keeping it safe and must
	guarantee it cannot leak outside user's application.

	For performance and security reasons the API secret token cannot be used directly for accessing executive API
	operations. Instead, the user has to ask for authorization first using this POST.
	The authorization process simply takes the API secret token and generates the authorization token with
	the time-restricted validity. This authorization token is self-contained and (currently) respects RFC 7519
	standard.

	It can be repeatedly used in executive API operations untill it expires. The expiration time can be parsed from
	the token however for the user convenience it is returned in the response in a human readable form of ISO 8601
	Extended Format. The user should ask for another authorization token sufficiently in advance.

	Each call of this operation generates a new authorization token with a new expiration time so it is possible to
	get a new one soon after its generation. However too frequent regeneration leads to performance loses and is
	discouraged.
	The best practice is to respect the expiration time and schedule re-generation according it, obviously with
	some time buffer covering the call latence. Asking for a new authorization token right before each executive
	API operation is an antipattern.

	consumes:
	- application/json
	produces:
	- application/json
	parameters:
	-
	name: body
	in: body
	description: JSON containing the API secret token
	required: true
	schema:
	$ref: '#/definitions/AuthorizationRequest'
	responses:
	200:
	description: Generates the authorization token with the time restriction.
	headers:
	Content-type:
	type: string
	description: application/json
	schema:
	$ref: '#/definitions/AuthorizationResponse'
	400:
	description: Unexpected error
	headers:
	Content-type:
	type: string
	description: application/problem+json
	schema:
	$ref: '#/definitions/ProblemDetail'
	403:
	description: Authorization error
	headers:
	Content-type:
	type: string
	description: application/problem+json
	schema:
	$ref: '#/definitions/ProblemDetailAuth'

	"/speech/jobs":
	x-summary: Speech Analytic Jobs
	x-description: \|
	All speech analytics jobs are asynchronous since the time between http request and response is often not
	sufficient for the job to be completed. Therefore task definitions are accepted by a single API call and results are sent back to the user defined callback when ready.
	post:
	tags:
	- Speech Jobs

	summary: Create a new composite analytic job
	description: \|
	Starts an analytic job as a composite request consisting of several tasks:
	- Statistics (optional)
	- Search for Phrases (optional)
	- Transcripts (in the future)

	At least one _task_ has to be specified.

	### Statistics

	Basic statistics are:
	- Total length of the audio
	- Cummulative cross-talk time
	- Mutual silence time
	- Talk times per channel

	All stats are reported in seconds.

	Stats are computed when

	statistics: {}

	key is present in the _tasks_ attribute.

	### Phrases

	This _embedded resource _phrase_set_ defines a set or list of text phrases in a specific
	language we want to look for.

	The _min_confidence_ parameter specifies the minimal confidence enabling to set the confidence
	threshold. Phrase findings with the confidence lower than the confidence thresholds are not
	reported which helps to reduce the number of false alarms at the speech engine level.

	There are two ways how to specify the phrase set:
	- Phrase List .. simple array of all phrases
	- Phrases Object .. with the minimal confidence specified for each phrase.

	### Recording

	There is a link in the job definition which specifies the audio URL.
	The audio URL must be accessible to the Speech Service. It might contain an opaque hash as
	a mean of a basic trust between consumer and the Speech Service.

	Recording represents the way the Speech API knows audio data.
	The supported audio format is:

	8kHz stereo WAV (both 16bit PCM and A-law)

	We may support different formats and different transport strategies in the future.
	Mono WAVs are also tolerated, however one channel per speaker condition is required i.e. mixing
	speakers in mono channels is not allowed. A single recording can store a conversation consisting
	one or more channels. Typically, the Recording is the stereo WAV where two speakers talk to each
	other, each speaker has a separate channel. However, a single recording (a single conversation)
	can be recorded in more WAVs with different offsets for channels. The only requirement is that
	a speech of more speakers must not mix in a single channel.

	#### Result Callback

	The client has to provide _links with the results_callback.
	Again, the URL can be opaque as in the case of recording audio.

	Please note that there are no exact guarantees w.r.t. the time between the job creation and
	sending back results.
	security:
	- Bearer: []
	consumes:
	- application/hal+json
	produces:
	- application/hal+json
	parameters:
	-
	name: body
	in: body
	description: HAL (JSON) describing the analytic job.
	required: true
	schema:
	$ref: '#/definitions/JobDescription'
	responses:
	202:
	description: Accepted the new asynchronous job
	headers:
	Content-type:
	type: string
	description: application/hal+json
	schema:
	$ref: '#/definitions/JobAccepted'
	400:
	description: Unexpected error
	headers:
	Content-type:
	type: string
	description: application/problem+json
	schema:
	$ref: '#/definitions/ProblemDetail'
	403:
	description: Authorization error
	headers:
	Content-type:
	type: string
	description: application/problem+json
	schema:
	$ref: '#/definitions/ProblemDetailAuth'

	"/any/path/to/consumer/provided/endpoint":
	x-summary: Callback Receiving Endpoint
	x-description: \|
	The client's endpoint is called with the URL provided by _links with the results_callback specified
	by Job Creation operation.

	post:
	tags:
	- Job Results

	summary: Receive results
	description: \|
	Inform Ytica API consumer about the results of asynchronous job by calling the endpoint.
	The endpoint URL must be accessible to the Speech Service and defined in _links section of
	the Job Creation operation.

	The client is informed about the job outcome (completed/failed).

	All specified tasks have their according tasks_result.
	consumes:
	- application/json
	produces:
	- application/json
	parameters:
	-
	name: body
	in: body
	description: JSON describing the result.
	required: true
	schema:
	$ref: '#/definitions/CallbackRequest'
	responses:
	200:
	description: Consumer informs the Speech Service that succesfuly received results.
	headers:
	Content-type:
	type: string
	description: application/hal+json
	schema:
	$ref: '#/definitions/CallbackResponse'
	400:
	description: Unexpected error
	headers:
	Content-type:
	type: string
	description: application/problem+json
	schema:
	$ref: '#/definitions/ProblemDetail'


	# }} m4 preprocessor

	definitions:

	# {{ m4 preprocessor

	AuthorizationRequest:
	title: The API secret token authenticating the user
	description: \|
	The secret information proving the user's identity in the context of Ytica API services.
	type: object
	properties:
	api_secret_token:
	type: string
	description: Authentication API Secret Token which proves the API consumer identity.
	required:
	- api_secret_token
	example:
	api_secret_token: '89281f03-7e0e-4e50-b06f-e1e5393aef76'

	AuthorizationResponse:
	title: The authorization of the user
	description: \|
	Authorization token and expiration information.
	properties:
	authorization_token:
	type: string
	description: The self-contained authorization token.
	expire:
	type: string
	description: Token expiration time respecting ISO 8601.
	required:
	- authorization_token
	- expire
	example:
	authorization_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ'
	expire: '2017-05-09T11:00:55.712Z'



	JobDescription:
	title: The composite speech analytic job.
	description: \|
	The resource representing the asynchronous speech analytic job consisting of several tasks.
	Any task binds a recording with any of:
	- simple statistics
	- phrase search
	- transcripts (in the future).
	Results are available via results_callback.
	type: object
	properties:
	_links:
	type: object
	properties:
	results_callback:
	description: \|
	Callback is triigerred by the Speech service when job results are ready.
	In the rare case of a failed job the callback is called with the content-type problem+json.
	type: object
	properties:
	href:
	type: string
	format: url
	required:
	- href
	recording_audio:
	description: The accessible location of the audio recording.
	type: object
	properties:
	href:
	type: string
	format: url
	required:
	- href
	required:
	- results_callback
	- recording_audio
	_embedded:
	type: object
	properties:
	phrase_set:
	$ref: '#/definitions/PhraseSet'
	tasks:
	type: object
	description: \|
	Tasks parameters define parts of the job. If the key is omitted the task will not be processed.
	At least one of
	- statistics
	- phrase_spotting
	must be present.
	properties:
	statistics:
	type: object
	description: Ask for simple recording statistics to be computed.
	phrase_spotting:
	type: object
	description: If the phrase_spotting task is specified the _embedded must contain the phrase_set.
	properties:
	min_confidence:
	type: number
	format: float
	minimum: 20.0
	description: Minimum confidence threshold allowing filtration (default for all phrases in PhraseSet).
	# anyOf:
	# - statistics
	# - phrase_spotting
	required:
	- _links
	- tasks
	example:
	_links:
	results_callback:
	href: 'http://example.com/results_endpoint/4354235_34_3255'
	recording_audio:
	href: 'http://example.com/external_storage/42/recordings/4354235_34.wav'
	_embedded:
	phrase_set:
	phrase_list:
	- hello
	- how are you
	language: en-US
	tasks:
	statistics: {}
	phrase_spotting:
	min_confidence: 30.0

	PhraseSet:
	title: Phrase Set
	description: \|
	This is the set of phrases to be searched in audio files.
	There are two ways of defining phrases: Using
	- phrase_list .. a simple array of phrase texts
	- phrases .. an array of phrase objects for an individual control of the minimal confidence threshold.
	type: object
	properties:
	phrase_list:
	type: array
	items:
	type: string
	description: Phrase texts
	phrases:
	type: array
	items:
	type: object
	properties:
	text:
	type: string
	description: Phrase text
	min_confidence:
	type: number
	format: float
	minimum: 20.0
	description: Minimal confidence threshold for a particular phrase
	required:
	- text
	language:
	type: string
	description: \|
	Language of the Phrase set (e.g. en-US).
	See https://tools.ietf.org/html/rfc5646 or http://www.lingoes.net/en/translator/langcode.htm
	required:
	- language
	# anyOf:
	# - phrase_list
	# - phrases
	example:
	phrase_list:
	- hello
	- how are you
	language: en-US


	ResultsStatistics:
	title: Results of the statistics task
	description: Simple cummulative information about speech/silence parts th the recording in audio channels.
	type: object
	properties:
	total_length:
	type: number
	format: float
	description: Total duration of the call (in seconds)
	cross_talk:
	type: number
	format: float
	description: Total duration of crosstalks (in seconds)
	cross_silence:
	type: number
	format: float
	description: Total duration of silence in all channels (in seconds)
	talk_times:
	type: array
	items:
	type: number
	format: float
	description: \|
	Cummulative duration of talk parts per channel (in seconds)
	Each array value coresponds with the audio channel.
	example:
	total_length: 480.1
	cross_silence: 201.34
	cross_talk: 11.2
	talk_times:
	- 87.45
	- 145.32

	ResultsPhrases:
	title: Result of the phrase search.
	description: Phrases found in the recording.
	type: object
	properties:
	phrases_found:
	type: array
	items:
	type: object
	description: 'Single phrase searched'
	properties:
	text:
	type: string
	description: 'A phrase text (echo from Phrases model)'
	findings:
	description: 'All occurrences found in the recording'
	type: array
	items:
	type: object
	properties:
	channel:
	type: integer
	description: 'Channel index (e.g. 0 or 1 for a stereo audio file)'
	from:
	type: number
	format: float
	description: 'Beginning of the phrase occurrence (in secs)'
	to:
	type: number
	format: float
	description: 'End of the phrase occurrence (in secs)'
	confidence:
	type: number
	format: float
	description: 'Phrase was found with this confidence'
	language:
	type: string
	description: \|
	Language of the Phrase set (e.g. en-US).
	See https://tools.ietf.org/html/rfc5646 or http://www.lingoes.net/en/translator/langcode.htm

	example:
	language: en-US
	phrases_found:
	-
	text: hello
	findings:
	-
	channel: 0
	from: 5.33
	to: 5.98
	confidence: 47.74
	-
	channel: 1
	from: 2.13
	to: 3.58
	confidence: 87.14
	-
	text: can i help ya
	-
	text: well not exactly
	-
	text: how are you
	findings:
	-
	channel: 1
	from: 4.13
	to: 3.76
	confidence: 77.14

	CallbackResponse:
	title: Succesful Callback Response
	description: An empty response required
	type: object
	additionalProperties: false

	CallbackRequest:
	title: Asynchronous analytic job response
	description: \|
	Asynchronous speech analytic results:
	- simple statistics
	- phrase search
	- transcripts (in the future).
	type: object
	properties:
	_links:
	type: object
	properties:
	recording_audio:
	description: The accessible location of the audio recording.
	type: object
	properties:
	href:
	type: string
	format: url
	required:
	- href
	required:
	- recording_audio
	outcome:
	type: string
	enum:
	- completed
	- failed
	tasks_result:
	type: object
	properties:
	statistics:
	$ref: '#/definitions/ResultsStatistics'
	phrase_spotting:
	$ref: '#/definitions/ResultsPhrases'
	required:
	- _links
	- outcome
	example:
	_embedded:
	recording:
	_links:
	audio:
	href: 'http://example.com/external_storage/42/recordings/4354235_34.wav'
	outcome: completed
	tasks_result:
	statistics:
	total_length: 480.1
	cross_silence: 201.34
	cross_talk: 11.2
	talk_times:
	- 87.45
	- 145.32
	phrase_spotting:
	language: en-US
	phrases_found:
	-
	text: hello
	findings:
	-
	channel: 0
	from: 5.33
	to: 5.98
	confidence: 47.74
	-
	channel: 1
	from: 2.13
	to: 3.58
	confidence: 87.14
	-
	text: can i help ya
	-
	text: well not exactly
	-
	text: how are you
	findings:
	-
	channel: 1
	from: 4.13
	to: 3.76
	confidence: 77.14


	JobAccepted:
	title: The analytics job was accepted.
	description: \|
	This is the information for the customer that the asynchronous job description was received.
	Related resources (audio and phrases) are also referenced here.
	type: object
	properties:
	status:
	type: string
	enum:
	- queued
	description: The status of the job. Currently, only 'queued' is supported.
	required:
	- status
	example:
	status: queued



	# shared in definitions:

	ProblemDetail:
	title: Normalized response in the case of problems.
	description: 'Please see https://tools.ietf.org/html/rfc7807'
	type: object
	properties:
	type:
	type: string
	format: url
	title:
	type: string
	status:
	type: number
	detail:
	type: string
	required:
	- title
	- detail
	example:
	type: https://developers.ytica.com/api/problems/bad-params
	title: Bad parameters
	detail: The required parameter missing.
	status: 400

	ProblemDetailAuth:
	title: Example response in the case of auth issues
	description: 'Please see https://tools.ietf.org/html/rfc7807'
	type: object
	properties:
	type:
	type: string
	format: url
	title:
	type: string
	status:
	type: number
	detail:
	type: string
	required:
	- title
	- detail
	example:
	type: https://developers.ytica.com/api/problems/auth-failed
	title: Authorization failed
	detail: Insufficient parmissions in the auth token.
	status: 403
	# }} m4 preprocessor