openapi: 3.1.0
info:
  title: SAP BI Tools SAP Analytics Cloud Administration Stories API
  description: RESTful API for SAP Analytics Cloud enabling programmatic access to system data stored on an SAP Analytics Cloud tenant. The API provides endpoints for managing stories, models, users, teams, calendars, and other resources. It supports SCIM 2.0 for user provisioning, OData for data access, and standard REST patterns for content management. Authentication uses OAuth 2.0 with SAML bearer assertion or authorization code grant flows.
  version: '1.0'
  contact:
    name: SAP Support
    url: https://support.sap.com/en/index.html
  termsOfService: https://www.sap.com/about/legal/terms-of-use.html
servers:
- url: https://{tenant}.{datacenter}.sapanalytics.cloud
  description: SAP Analytics Cloud Tenant
  variables:
    tenant:
      default: my-tenant
      description: The SAP Analytics Cloud tenant name
    datacenter:
      default: eu1
      description: The data center region (e.g., eu1, eu10, us1, us10, ap1)
security:
- oauth2: []
tags:
- name: Stories
  description: Manage analytic stories including dashboards and reports. Stories are the primary visualization artifact in SAP Analytics Cloud.
paths:
  /api/v1/stories:
    get:
      operationId: listStories
      summary: SAP BI Tools List stories
      description: Retrieves a list of stories available on the SAP Analytics Cloud tenant. Supports query parameters to include additional metadata such as models used in each story. Returns a JSON array of story objects with their identifiers, names, descriptions, and metadata.
      tags:
      - Stories
      parameters:
      - $ref: '#/components/parameters/IncludeParam'
      responses:
        '200':
          description: Successfully retrieved list of stories
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Story'
        '401':
          description: Unauthorized - invalid or missing authentication token
        '403':
          description: Forbidden - insufficient permissions
  /api/v1/stories/{storyId}:
    get:
      operationId: getStory
      summary: SAP BI Tools Get a story by ID
      description: Retrieves detailed information about a specific story identified by its unique story ID. Returns the story metadata, structure, and optionally the models used within it.
      tags:
      - Stories
      parameters:
      - $ref: '#/components/parameters/StoryIdParam'
      - $ref: '#/components/parameters/IncludeParam'
      responses:
        '200':
          description: Successfully retrieved story details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Story'
        '401':
          description: Unauthorized - invalid or missing authentication token
        '404':
          description: Story not found
components:
  parameters:
    StoryIdParam:
      name: storyId
      in: path
      required: true
      description: The unique identifier of the story
      schema:
        type: string
    IncludeParam:
      name: include
      in: query
      description: Comma-separated list of related resources to include in the response (e.g., models)
      schema:
        type: string
  schemas:
    Story:
      type: object
      description: Represents an analytic story in SAP Analytics Cloud. Stories are the primary visualization artifact containing charts, tables, and other components for data analysis.
      properties:
        id:
          type: string
          description: The unique identifier of the story
        name:
          type: string
          description: The display name of the story
        description:
          type: string
          description: A text description of the story
        createdTime:
          type: string
          format: date-time
          description: The timestamp when the story was created
        modifiedTime:
          type: string
          format: date-time
          description: The timestamp when the story was last modified
        createdBy:
          type: string
          description: The user ID of the story creator
        modifiedBy:
          type: string
          description: The user ID of the last modifier
        resourceType:
          type: string
          description: The type of resource (STORY)
        models:
          type: array
          description: List of models used in the story
          items:
            $ref: '#/components/schemas/ModelReference'
    ModelReference:
      type: object
      description: A reference to a model used within a story
      properties:
        id:
          type: string
          description: The unique identifier of the model
        name:
          type: string
          description: The display name of the model
        description:
          type: string
          description: A text description of the model
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authentication using SAML bearer assertion or authorization code grant flow.
      flows:
        authorizationCode:
          authorizationUrl: https://{tenant}.authentication.{region}.hana.ondemand.com/oauth/authorize
          tokenUrl: https://{tenant}.authentication.{region}.hana.ondemand.com/oauth/token
          scopes: {}
externalDocs:
  description: SAP Analytics Cloud REST API Documentation
  url: https://help.sap.com/docs/SAP_ANALYTICS_CLOUD/14cac91febef464dbb1efce20e3f1613/3ccfab3348dd407db089accb66cff9a2.html