> Agent-readable docs index: /llms.txt. Fetch only the needed Markdown pages first; use /docs.zip only for broad search after checking /docs-manifest.json or /docs.zip.sha256.

# KOS OpenAPI

KOS OpenAPI is available only to development teams at hospitals that use the KOS solution.

For details, contact the KOS sales representative for your hospital.

This document can be checked through the [OpenAPI Spec](/openapi.yaml) file.

### API Request Method

1. KOS OpenAPI uses POST for all requests, including queries, updates, and deletions.

2. Except for authentication APIs, every request must include an Auth Token in the `Authorization` header. For details, see [Authentication](/docs/openapi/authorization).

3. Most error responses return the `400` status code. Check the error response details to identify the cause. For details, see [Error Response](#error-response). If the Auth Token is missing or expired, the API returns `401`, and if the [Call Limit](#call-limit) is exceeded, it returns `429`.

### Date And Time Format

Fields that convey date or time follow the format specified in each field description.

Fields documented as `format: date-time` use [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date-time strings. Fields specified as UTC deliver values in the UTC timezone.

### Country Code Format

Country codes used in product and target country queries are [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) strings.

The country code for phone numbers follows the `countryCode` description in the phone number schema.

<Callout type="caution">
<p>For target countries used to decide which products to show and which prices to apply, <strong>"Other countries" is represented as <code>ETC</code></strong>.</p>
<p>For details, see <a href="/docs/openapi/targetcountry">Target Country</a>.</p>
</Callout>

### Error Response

When a query or command cannot be processed successfully, the API returns a `400` HTTP status code with an error response like this:

```json
{
  "status": 400,
  "message": "InvalidCommandException",
  "className": "InvalidCommandException",
  "errorProperties": [
    {
      "key": "{{ Key }}",
      "reason": "{{ ErrorReason }}"
    }
  ]
}
```

- `key`: the missing field name or the field name that has an invalid value
- `reason`: the error reason
  - `TooShort`: the string is too short
  - `TooLong`: the string is too long
  - `Required`: a required field is missing
  - `Duplicated`: duplicated value
  - `InvalidTimeRange`: time range validation failed
  - `NotAvailable`: not available
  - `NotFound`: target not found
  - `TooSmall`: the value is too small
  - `TooBig`: the value is too large

### Call Limit

If more than 3,000 calls are made from the same IP within the last 1 minute, the request will be blocked and a `429` status code will be returned. The number of calls is summed by IP regardless of API Key or endpoint.

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 60
```

```json
{
  "status": 429,
  "className": "TooManyRequests",
  "message": "Too many requests. Please retry after 1 minute."
}
```

Please retry after the time (in seconds) specified in the `Retry-After` header has passed. The call limit may change according to KOS policy.


## Endpoints

- [Staff](/en/docs/openapi/account.md): 1
- [Authentication](/en/docs/openapi/authorization.md): 1
- [Image](/en/docs/openapi/image.md): 2
- [Prepaid Card](/en/docs/openapi/prepaid-card.md): 3
- [Product](/en/docs/openapi/product.md): 15
- [Payment](/en/docs/openapi/purchase.md): 3
- [Satisfaction Survey](/en/docs/openapi/satisfactionsurvey.md): 1
- [Schedule](/en/docs/openapi/schedule.md): 37
- [Statistics](/en/docs/openapi/statistics.md): 7
- [Target Country](/en/docs/openapi/target-country.md): 1
- [Treatment Ticket](/en/docs/openapi/ticket.md): 1
- [Client](/en/docs/openapi/visitor.md): 9

## Schemas

[Schemas](/en/docs/openapi/~schemas.md)