S
Scholé
Integration API
SDK Generation

Generate a Client Library

The Scholé API ships an OpenAPI 3.1 specification. Any OpenAPI-compatible generator can produce a fully typed client in your language of choice — no hand-written HTTP layer needed.

How It Works

openapi-generator reads the machine-readable spec at /api/v1/schema/ and emits a complete, documented client — models, API classes, auth helpers, and type annotations.

Step 1 — Download the spec

Fetch the canonical OpenAPI JSON from the live schema endpoint or save it to a file and check it into your repo.

Step 2 — Run the generator

Choose a generator for your language, point it at the spec, and get a ready-to-import package with full type coverage.

Download the OpenAPI spec

bash
# Save to file (recommended — pin the spec alongside your integration code)
curl -o schole-api.json https://app.schole.ai/api/v1/schema/

# Or reference the live URL directly in generator commands
# https://app.schole.ai/api/v1/schema/
Pin your spec version
Save schole-api.json at a specific commit so your generated client stays stable across Scholé releases. Regenerate deliberately when you need to pick up schema changes.
Python

We recommend openapi-python-client for idiomatic Python clients with Pydantic v2 models, or the universal openapi-generator-cli if you prefer a more Java-flavoured style.

Option A — openapi-python-client (recommended)

bash
pip install openapi-python-client

# Generate from the live spec
openapi-python-client generate \
  --url https://app.schole.ai/api/v1/schema/ \
  --output-path ./schole-client

# Or from a saved file
openapi-python-client generate \
  --path ./schole-api.json \
  --output-path ./schole-client

Option B — openapi-generator-cli

bash
# Requires Java 11+ on PATH
pip install openapi-generator-cli   # thin Python wrapper

openapi-generator-cli generate \
  -i schole-api.json \
  -g python \
  -o ./schole-client-py \
  --package-name schole_client

Usage example

python
from schole_client import AuthenticatedClient
from schole_client.api.users import v1_user_list
from schole_client.models import UserProfile

# Create a client with your OAuth2 / JWT bearer token
client = AuthenticatedClient(
    base_url="https://app.schole.ai",
    token="YOUR_ACCESS_TOKEN",
)

# List users — returns a paginated response with typed models
with client as c:
    response = v1_user_list.sync(client=c, page_size=50)
    for user in response.results:
        print(user.email, user.full_name)
Java

Use the official openapi-generator Maven or Gradle plugin to generate a client with OkHttp and Gson (default) or switch to Retrofit2 / Spring WebClient.

Maven plugin

xml — pom.xml
<plugin>
  <groupId>org.openapitools</groupId>
  <artifactId>openapi-generator-maven-plugin</artifactId>
  <version>7.6.0</version>
  <executions>
    <execution>
      <goals><goal>generate</goal></goals>
      <configuration>
        <inputSpec>${project.basedir}/src/main/resources/schole-api.json</inputSpec>
        <generatorName>java</generatorName>
        <apiPackage>io.schole.client.api</apiPackage>
        <modelPackage>io.schole.client.model</modelPackage>
        <configOptions>
          <library>okhttp-gson</library>
          <dateLibrary>java8</dateLibrary>
        </configOptions>
      </configuration>
    </execution>
  </executions>
</plugin>
bash
mvn openapi-generator:generate

Usage example

java
import io.schole.client.ApiClient;
import io.schole.client.Configuration;
import io.schole.client.api.UsersApi;
import io.schole.client.model.PaginatedUserProfileList;

ApiClient client = Configuration.getDefaultApiClient();
client.setBasePath("https://app.schole.ai");
client.setBearerToken("YOUR_ACCESS_TOKEN");

UsersApi usersApi = new UsersApi(client);
PaginatedUserProfileList page = usersApi.v1UserList(
    null,   // search
    1,      // page
    50      // pageSize
);
page.getResults().forEach(u ->
    System.out.println(u.getEmail() + " — " + u.getFullName()));
.NET

NSwag produces idiomatic C# clients targeting .NET 6+ with full nullable-reference-type support. Alternatively, use Kiota (Microsoft's official OpenAPI client generator).

NSwag CLI

bash
dotnet tool install -g NSwag.ConsoleCore

nswag openapi2csclient \
  /input:schole-api.json \
  /namespace:Schole.Client \
  /output:ScholApiClient.cs \
  /generateClientClasses:true \
  /generateDtoTypes:true \
  /injectHttpClient:true

Kiota (Microsoft) — alternative

bash
dotnet tool install --global Microsoft.OpenApi.Kiota

kiota generate \
  --openapi schole-api.json \
  --language CSharp \
  --class-name ScholApiClient \
  --namespace-name Schole.Client \
  --output ./ScholClient

Usage example (NSwag)

java
// C#
using Schole.Client;

var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "YOUR_ACCESS_TOKEN");

var client = new ScholApiClient("https://app.schole.ai", http);

var page = await client.V1UserListAsync(search: null, page: 1, pageSize: 50);
foreach (var user in page.Results)
    Console.WriteLine($"{user.Email} — {user.FullName}");
JavaScript / TypeScript

openapi-typescript-codegen produces typed TypeScript classes with fetch or axios. For React Query or SWR users consider orval, which also generates hooks.

openapi-typescript-codegen

bash
npm install -g @hey-api/openapi-ts

openapi-ts \
  --input  https://app.schole.ai/api/v1/schema/ \
  --output ./src/api/schole \
  --client fetch

orval (with React Query hooks)

bash
npm install -D orval

# orval.config.ts
# ---
# import { defineConfig } from 'orval';
# export default defineConfig({
#   schole: {
#     input: { target: 'https://app.schole.ai/api/v1/schema/' },
#     output: {
#       target: './src/api/schole.ts',
#       client: 'react-query',
#       baseUrl: 'https://app.schole.ai',
#     },
#   },
# });

npx orval

Usage example (fetch)

javascript
import { UsersService, OpenAPI } from './src/api/schole';

// Configure auth once
OpenAPI.BASE   = 'https://app.schole.ai';
OpenAPI.TOKEN  = 'YOUR_ACCESS_TOKEN'; // or a () => Promise factory

// List users
const page = await UsersService.v1UserList({ pageSize: 50 });
for (const user of page.results) {
  console.log(user.email, user.full_name);
}
Keeping Your Client Up-to-Date

When Scholé ships a new API version, regenerate your client from the updated spec. We recommend automating this in CI:

yaml — GitHub Actions example
# .github/workflows/update-api-client.yml (excerpt)
- name: Download latest spec
  run: curl -o schole-api.json https://app.schole.ai/api/v1/schema/

- name: Regenerate Python client
  run: |
    pip install openapi-python-client
    openapi-python-client update --path schole-api.json

- name: Open PR with updated client
  uses: peter-evans/create-pull-request@v6

See Versioning & Lifecycle for how Scholé communicates breaking vs non-breaking spec changes.