Quickstart

For a new app, request access first and confirm your integration settings with the platform team. The steps below describe the Open API v1 OAuth flow.

1. Register your client — once per origin. Redirect URIs must be https (http://localhost and loopback IPs are allowed in development) and must not contain a fragment. Persist the returned client_id.

   POST https://api.harperharbor.com/oauth/register
   Content-Type: application/json
   
   { "client_name": "Your app",
     "redirect_uris": ["https://app.example.com/oauth/callback"],
     "grant_types": ["authorization_code", "refresh_token"] }

2. Send the user to authorize — authorization code with PKCE (S256). Include the resource indicator so the token is bound to the Open API audience. This is a full-page navigation, not XHR.

   https://api.harperharbor.com/oauth/authorize
     ?response_type=code
     &client_id=…
     &redirect_uri=https://app.example.com/oauth/callback
     &resource=https://api.harperharbor.com/open/v1
     &state=…
     &code_challenge=…             # base64url(sha256(verifier))
     &code_challenge_method=S256

3. Exchange the code for an access token and a refresh token.

   POST https://api.harperharbor.com/oauth/token
   Content-Type: application/x-www-form-urlencoded
   
   grant_type=authorization_code&code=…&client_id=…
   &redirect_uri=…&code_verifier=…&resource=https://api.harperharbor.com/open/v1

4. Make the first call.

   curl

   curl https://api.harperharbor.com/open/v1/me \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     -H "language: en"

   TypeScript

   const res = await fetch("https://api.harperharbor.com/open/v1/me", {
     headers: { Authorization: `Bearer ${accessToken}`, language: "en" },
   });
   const me = await res.json(); // { id: 100001, nickname: "Aoi" }

   Python

   import requests
   r = requests.get("https://api.harperharbor.com/open/v1/me",
                    headers={"Authorization": f"Bearer {access_token}", "language": "en"})
   me = r.json()  # public numeric id only

Then play a card

GET  /open/v1/role/detail?roleId=…          # what the card needs
POST /open/v1/conversation/start            # { roleId, greetingIndex? }
POST /open/v1/conversation/ws-ticket        # one-time ticket for the stream

Continue with Conversation loop and Streaming.