Get started with Osyra

Send one real Chat Completions request through Osyra Edge and capture the request ID that connects the response to Osyra's audit trail.

This guide uses cURL for the first call because the response headers are part of the result. After that call succeeds, you can repeat the request with Python or TypeScript. The request body keeps the OpenAI shape. Osyra adds authentication, policy, routing, usage, and evidence controls around the call.

By the end of this guide, you will have:

1. sent a model request through Osyra;
2. verified that the response contains assistant output; and
3. captured the server-issued X-Request-ID for application logs and operator support.

Prerequisites

You need:

• an Osyra Edge base URL for an active environment;
• an IAM-issued Osyra API key;
• a chat-capable model ID assigned by the deployment operator; and
• cURL and jq installed locally.

An Osyra API key has this exact shape:

osy_(sandbox|test|live)_<43 base64url characters>

The plaintext is shown once. Store it in a secret manager. Do not put it in source control, screenshots, shell history, or support messages.

1. Set the Edge URL

Choose the environment that your deployment owner confirmed is active.

export OSYRA_BASE_URL="https://api.osyra.ai/v1"

2. Set the credential and model

Read the key without echoing it to the terminal, then set the model ID provided for your environment.

printf "Osyra API key: "
IFS= read -r -s OSYRA_API_KEY
printf "\n"
export OSYRA_API_KEY
export OSYRA_MODEL="<chat-model-id-from-your-deployment>"

If you need to discover registered model IDs, query the deployment catalog:

curl --fail-with-body --silent --show-error \
  "${OSYRA_BASE_URL}/models" \
  -H "X-Api-Key: ${OSYRA_API_KEY}" |
  jq -r '.data[].id'

Catalog membership proves that a model is registered. It does not prove that the current workspace policy authorizes a request to that model.

3. Send the request with cURL

This path saves the headers and body separately. Both are required for the next two steps.

headers_file="$(mktemp)"
response_file="$(mktemp)"
 
curl --fail-with-body --silent --show-error \
  -D "${headers_file}" \
  -o "${response_file}" \
  "${OSYRA_BASE_URL}/chat/completions" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OSYRA_API_KEY}" \
  -d "{
    \"model\": \"${OSYRA_MODEL}\",
    \"messages\": [
      {\"role\": \"user\", \"content\": \"Reply with one sentence about verified AI.\"}
    ]
  }"
 
jq -e '.choices[0].message.content | type == "string"' "${response_file}"
jq -r '.choices[0].message.content' "${response_file}"

4. Capture the request ID

Read the server-issued request ID from the saved response headers:

OSYRA_REQUEST_ID="$(
  awk 'tolower($1) == "x-request-id:" {gsub("\r", "", $2); print $2}' \
    "${headers_file}"
)"
 
test -n "${OSYRA_REQUEST_ID}"
printf 'Request ID: %s\n' "${OSYRA_REQUEST_ID}"

Every Edge response carries X-Request-ID. Keep it with your application log entry. It is the identifier support and operators use to find the request trace.

5. Confirm what the request proved

A successful assistant response proves that the request reached the model through Edge. A non-empty request ID proves that Edge assigned the correlation key returned with that response. Keep both in your application log.

This result does not prove that every downstream evidence property is present, and the current Console does not provide request-ID search across audit and evidence records. Give the request ID to support or an operator when a trace must be correlated.

Remove the temporary response files after you have recorded the result:

rm -f "${headers_file}" "${response_file}"
unset headers_file response_file

Continue with:

• Authentication for API keys, OAuth service identities, and interactive OAuth;
• Policy as Code to understand authorization at the edge;
• Vendor-neutral routing to understand provider and model selection; and
• Verified Memory for OME evidence and offline verification.

6. Use an application client

After the cURL path succeeds, send the same request from your application.

python -m pip install openai

import os
from openai import OpenAI
 
client = OpenAI(
    api_key=os.environ["OSYRA_API_KEY"],
    base_url=os.environ["OSYRA_BASE_URL"],
)
 
response = client.chat.completions.create(
    model=os.environ["OSYRA_MODEL"],
    messages=[
        {
            "role": "user",
            "content": "Reply with one sentence about verified AI.",
        }
    ],
)
 
print(response.choices[0].message.content)

python quickstart.py

These examples confirm application compatibility, but they only print the assistant message. They do not replace Steps 3 through 5 because they discard the response headers. In production, retain raw response metadata and log X-Request-ID using an API supported by your pinned client version.

Troubleshooting

| Status | Meaning | What to check | |---|---|---| | 400 | Conflicting or malformed request | Send exactly one credential channel and a valid Chat Completions body. | | 401 | Credential rejected | Confirm the key was copied exactly once, has not expired, and has not been revoked. | | 403 | Policy or workspace denied the request | Confirm the model is allowed for the credential's authoritative workspace. | | 429 | Rate or quota limit reached | Read Retry-After and retry with bounded backoff. | | 501 OSY-SERVER-9050 | API key lifecycle is not active | Ask the deployment owner to enable API key cryptography and its KMS key. | | 503 OSY-SERVER-9002 | IAM verification is unavailable | Check IAM health and retry after the service recovers. |

Do not add an Authorization header beside X-Api-Key to fix a 401. Edge rejects dual credentials before IAM or JWT validation.

Native Osyra SDKs

The native Python and Go gateway SDKs add typed Osyra headers for workspace assertion, semantic cache behavior, and PII masking. They are currently repository-resident and are not published to PyPI or pkg.go.dev. Follow the Python gateway SDK or Go gateway SDK guide when you are working from the Osyra source tree.