gh-secondsky-sap-skills-skills-sap-ai-core/references/api-reference.md

# SAP AI Core API Reference

Complete API reference for SAP AI Core.

**Documentation Source:** [https://github.com/SAP-docs/sap-artificial-intelligence/tree/main/docs/sap-ai-core](https://github.com/SAP-docs/sap-artificial-intelligence/tree/main/docs/sap-ai-core)

---

## Authentication

### OAuth Token Endpoint

```bash
curl -X POST "[https://<id-zone>.authentication.<region>.hana.ondemand.com/oauth/token"](https://<id-zone>.authentication.<region>.hana.ondemand.com/oauth/token") \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET"
```

### Required Headers

| Header | Description |
|--------|-------------|
| `Authorization` | `Bearer <token>` |
| `AI-Resource-Group` | Resource group name (e.g., `default`) |
| `Content-Type` | `application/json` |

---

## Base URLs

| Environment | URL Pattern |
|-------------|-------------|
| AI API | `[https://api.ai.prod.<region>.hana.ondemand.com`](https://api.ai.prod.<region>.hana.ondemand.com`) |
| Inference | `[https://api.ai.prod.<region>.hana.ondemand.com/v2/inference/deployments/<deployment-id>`](https://api.ai.prod.<region>.hana.ondemand.com/v2/inference/deployments/<deployment-id>`) |
| OAuth | `[https://<id-zone>.authentication.<region>.hana.ondemand.com/oauth/token`](https://<id-zone>.authentication.<region>.hana.ondemand.com/oauth/token`) |

**Regions:** `eu10`, `eu11`, `us10`, `us21`, `jp10`, `ap10`, `ap11`

---

## API Versioning

All endpoints use the `/v2/*` versioned routes:
- `/v2/lm/*` - Language model operations
- `/v2/inference/*` - Inference deployments
- `/v2/admin/*` - Administrative operations (secrets, repositories)

---

## Scenarios

### List Scenarios

```bash
GET $AI_API_URL/v2/lm/scenarios
```

**Response:**
```json
{
  "count": 2,
  "resources": [
    {
      "id": "foundation-models",
      "name": "Foundation Models",
      "description": "Access to generative AI models"
    },
    {
      "id": "orchestration",
      "name": "Orchestration",
      "description": "Unified model access with pipeline features"
    }
  ]
}
```

---

## Models

### List Available Models

```bash
GET $AI_API_URL/v2/lm/scenarios/foundation-models/models
```

**Response:**
```json
{
  "count": 50,
  "resources": [
    {
      "model": "gpt-4o",
      "accessType": "Remote",
      "displayName": "GPT-4o",
      "provider": "azure-openai",
      "executableId": "azure-openai",
      "versions": [
        {
          "name": "2024-05-13",
          "isLatest": true,
          "capabilities": ["text-generation", "chat"],
          "contextLength": 128000,
          "inputCost": 5.0,
          "outputCost": 15.0,
          "isStreamingSupported": true
        }
      ]
    }
  ]
}
```

---

## Configurations

### Create Configuration

```bash
POST $AI_API_URL/v2/lm/configurations
```

**Request Body:**
```json
{
  "name": "my-config",
  "executableId": "azure-openai",
  "scenarioId": "foundation-models",
  "parameterBindings": [
    {"key": "modelName", "value": "gpt-4o"},
    {"key": "modelVersion", "value": "latest"}
  ],
  "inputArtifactBindings": []
}
```

**Response:**
```json
{
  "id": "abc123-def456-ghi789",
  "message": "Configuration created"
}
```

### List Configurations

```bash
GET $AI_API_URL/v2/lm/configurations
```

**Query Parameters:**
| Parameter | Description |
|-----------|-------------|
| `scenarioId` | Filter by scenario |
| `executableId` | Filter by executable |
| `$top` | Limit results |
| `$skip` | Skip results |

### Get Configuration

```bash
GET $AI_API_URL/v2/lm/configurations/{configurationId}
```

### Delete Configuration

```bash
DELETE $AI_API_URL/v2/lm/configurations/{configurationId}
```

---

## Deployments

### Create Deployment

```bash
POST $AI_API_URL/v2/lm/deployments
```

**Request Body:**
```json
{
  "configurationId": "<configuration-id>",
  "ttl": "24h"
}
```

**TTL Format:** Natural numbers with units: `m` (minutes), `h` (hours), `d` (days)
- Valid: `5m`, `2h`, `7d`
- Invalid: `4.5h`, `4h30m` (fractional and combined units not supported)
- **Tip:** Convert combined durations to a single unit (e.g., `270m` instead of `4h30m`)

**Response:**
```json
{
  "id": "d12345-abcd-efgh",
  "deploymentUrl": "[https://...",](https://...",)
  "status": "PENDING",
  "message": "Deployment created"
}
```

### Get Deployment

```bash
GET $AI_API_URL/v2/lm/deployments/{deploymentId}
```

**Response:**
```json
{
  "id": "d12345-abcd-efgh",
  "configurationId": "c12345-abcd",
  "configurationName": "my-config",
  "scenarioId": "foundation-models",
  "status": "RUNNING",
  "statusMessage": "",
  "deploymentUrl": "[https://...",](https://...",)
  "createdAt": "2024-01-15T10:00:00Z",
  "modifiedAt": "2024-01-15T10:05:00Z"
}
```

### Deployment Statuses

| Status | Description |
|--------|-------------|
| `UNKNOWN` | Initial state |
| `PENDING` | Starting up |
| `RUNNING` | Active, serving requests |
| `STOPPING` | Shutting down |
| `STOPPED` | Inactive |
| `DEAD` | Failed |

### List Deployments

```bash
GET $AI_API_URL/v2/lm/deployments
```

### Update Deployment

```bash
PATCH $AI_API_URL/v2/lm/deployments/{deploymentId}
```

**Request Body:**
```json
{
  "configurationId": "<new-configuration-id>"
}
```

### Stop Deployment

```bash
PATCH $AI_API_URL/v2/lm/deployments/{deploymentId}
```

**Request Body:**
```json
{
  "targetStatus": "STOPPED"
}
```

### Delete Deployment

```bash
DELETE $AI_API_URL/v2/lm/deployments/{deploymentId}
```

---

## Executions

### Create Execution

```bash
POST $AI_API_URL/v2/lm/executions
```

**Request Body:**
```json
{
  "configurationId": "<configuration-id>"
}
```

### Get Execution

```bash
GET $AI_API_URL/v2/lm/executions/{executionId}
```

### Execution Statuses

| Status | Description |
|--------|-------------|
| `UNKNOWN` | Initial state |
| `PENDING` | Queued |
| `RUNNING` | Executing |
| `COMPLETED` | Finished successfully |
| `DEAD` | Failed |
| `STOPPED` | Manually stopped |

### List Executions

```bash
GET $AI_API_URL/v2/lm/executions
```

### Stop Execution

```bash
PATCH $AI_API_URL/v2/lm/executions/{executionId}
```

**Request Body:**
```json
{
  "targetStatus": "STOPPED"
}
```

### Delete Execution

```bash
DELETE $AI_API_URL/v2/lm/executions/{executionId}
```

### Get Execution Logs

```bash
GET $AI_API_URL/v2/lm/executions/{executionId}/logs
```

---

## Artifacts

### Register Artifact

```bash
POST $AI_API_URL/v2/lm/artifacts
```

**Request Body:**
```json
{
  "name": "training-data",
  "kind": "dataset",
  "url": "ai://<object-store>/<path>",
  "scenarioId": "<scenario-id>",
  "description": "Training dataset"
}
```

**Artifact Kinds:**
- `dataset`: Training data
- `model`: Trained model
- `resultset`: Inference results
- `other`: Other artifacts

### Get Artifact

```bash
GET $AI_API_URL/v2/lm/artifacts/{artifactId}
```

### List Artifacts

```bash
GET $AI_API_URL/v2/lm/artifacts
```

---

## Resource Groups

### Create Resource Group

```bash
POST $AI_API_URL/v2/admin/resourceGroups
```

**Request Body:**
```json
{
  "resourceGroupId": "my-resource-group"
}
```

### List Resource Groups

```bash
GET $AI_API_URL/v2/admin/resourceGroups
```

### Delete Resource Group

```bash
DELETE $AI_API_URL/v2/admin/resourceGroups/{resourceGroupId}
```

---

## Secrets

### Create Generic Secret

```bash
POST $AI_API_URL/v2/admin/secrets
```

**Request Body:**
```json
{
  "name": "my-secret",
  "data": {
    "key1": "value1",
    "key2": "value2"
  }
}
```

### Create Object Store Secret

```bash
POST $AI_API_URL/v2/admin/objectStoreSecrets
```

**AWS S3:**
```json
{
  "name": "default",
  "type": "S3",
  "pathPrefix": "my-bucket/path",
  "data": {
    "AWS_ACCESS_KEY_ID": "<key>",
    "AWS_SECRET_ACCESS_KEY": "<secret>"
  }
}
```

### List Secrets

```bash
GET $AI_API_URL/v2/admin/secrets
```

### Delete Secret

```bash
DELETE $AI_API_URL/v2/admin/secrets/{secretName}
```

---

## Meta API

### Get Runtime Capabilities

```bash
GET $AI_API_URL/lm/meta
```

**Response:**
```json
{
  "capabilities": {
    "logs.executions": true,
    "logs.deployments": true,
    "multitenant": true,
    "shareable": false,
    "staticDeployments": true,
    "userDeployments": true,
    "userExecutions": true,
    "timeToLiveDeployments": true,
    "analytics": true,
    "bulkUpdates": true,
    "executionSchedules": true
  },
  "limits": {
    "deployments.maxRunningCount": 10,
    "executions.maxRunningCount": 10,
    "minimumFrequencyHour": 1,
    "timeToLiveDeployments.minimum": "5m",
    "timeToLiveDeployments.maximum": "90d"
  },
  "extensions": {
    "analytics": "1.0",
    "metrics": "1.0",
    "resourceGroups": "1.0",
    "dataset": "1.0"
  }
}
```

---

## Orchestration API

### Chat Completion

```bash
POST $ORCHESTRATION_URL/v2/completion
```

**Request Body:**
```json
{
  "config": {
    "module_configurations": {
      "llm_module_config": {
        "model_name": "gpt-4o",
        "model_version": "latest",
        "model_params": {
          "max_tokens": 1000,
          "temperature": 0.7
        }
      },
      "templating_module_config": {
        "template": [
          {"role": "system", "content": "{{?system}}"},
          {"role": "user", "content": "{{?user}}"}
        ]
      }
    }
  },
  "input_params": {
    "system": "You are a helpful assistant.",
    "user": "Hello!"
  }
}
```

### Streaming Completion

```bash
POST $ORCHESTRATION_URL/v2/completion
```

**Request Body:**
```json
{
  "config": {
    "module_configurations": {
      "llm_module_config": {
        "model_name": "gpt-4o",
        "model_version": "latest",
        "model_params": {
          "stream": true
        }
      },
      "templating_module_config": {
        "template": [{"role": "user", "content": "{{?prompt}}"}]
      }
    }
  },
  "input_params": {"prompt": "Tell me a story"}
}
```

### Embeddings

```bash
POST $ORCHESTRATION_URL/v2/embeddings
```

**Request Body:**
```json
{
  "config": {
    "module_configurations": {
      "embedding_module_config": {
        "model_name": "text-embedding-3-large",
        "model_version": "latest",
        "model_params": {
          "encoding_format": "float",
          "dimensions": 1024
        }
      }
    }
  },
  "input": ["Text to embed"]
}
```

---

## Grounding API

### Create Pipeline

```bash
POST $AI_API_URL/v2/lm/groundingPipelines
```

**Request Body (SharePoint):**
```json
{
  "name": "hr-docs-pipeline",
  "configuration": {
    "dataSource": {
      "type": "sharepoint",
      "configuration": {
        "siteUrl": "[https://company.sharepoint.com/sites/HR",](https://company.sharepoint.com/sites/HR",)
        "folderPath": "/Documents/Policies"
      }
    },
    "secretName": "sharepoint-secret"
  }
}
```

### List Pipelines

```bash
GET $AI_API_URL/v2/lm/groundingPipelines
```

### Delete Pipeline

```bash
DELETE $AI_API_URL/v2/lm/groundingPipelines/{pipelineId}
```

---

## Error Responses

### Standard Error Format

```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "requestId": "req-12345",
    "target": "deployments"
  }
}
```

### Common Error Codes

| Code | HTTP Status | Description |
|------|-------------|-------------|
| `UNAUTHORIZED` | 401 | Invalid or expired token |
| `FORBIDDEN` | 403 | Missing permissions or quota exceeded |
| `NOT_FOUND` | 404 | Resource not found |
| `CONFLICT` | 409 | Resource already exists |
| `QUOTA_EXCEEDED` | 429 | Rate limit or quota exceeded |
| `INTERNAL_ERROR` | 500 | Server error |

---

## Bulk Operations

### Bulk Update Deployments

```bash
PATCH $AI_API_URL/v2/lm/deployments
```

**Request Body:**
```json
{
  "deployments": [
    {"id": "dep1", "targetStatus": "STOPPED"},
    {"id": "dep2", "targetStatus": "STOPPED"}
  ]
}
```

**Limit:** 100 items per request

### Bulk Delete Deployments

```bash
DELETE $AI_API_URL/v2/lm/deployments
```

**Request Body:**
```json
{
  "deploymentIds": ["dep1", "dep2", "dep3"]
}
```

---

## Schedules

### Create Schedule

```bash
POST $AI_API_URL/v2/lm/executionSchedules
```

**Request Body:**
```json
{
  "configurationId": "<config-id>",
  "cron": "0 0 * * *",
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-12-31T23:59:59Z"
}
```

**Cron Format:** `minute hour day month weekday`

### List Schedules

```bash
GET $AI_API_URL/v2/lm/executionSchedules
```

### Delete Schedule

```bash
DELETE $AI_API_URL/v2/lm/executionSchedules/{scheduleId}
```

---

## Documentation Links

- AI API Overview: [https://github.com/SAP-docs/sap-artificial-intelligence/blob/main/docs/sap-ai-core/ai-api-overview-716d4c3.md](https://github.com/SAP-docs/sap-artificial-intelligence/blob/main/docs/sap-ai-core/ai-api-overview-716d4c3.md)
- Configurations: [https://github.com/SAP-docs/sap-artificial-intelligence/blob/main/docs/sap-ai-core/create-configurations-884ae34.md](https://github.com/SAP-docs/sap-artificial-intelligence/blob/main/docs/sap-ai-core/create-configurations-884ae34.md)
- Deployments: [https://github.com/SAP-docs/sap-artificial-intelligence/blob/main/docs/sap-ai-core/deploy-models-dd16e8e.md](https://github.com/SAP-docs/sap-artificial-intelligence/blob/main/docs/sap-ai-core/deploy-models-dd16e8e.md)