Quick start

Prefer to just dive in? Here's everything you need to get started immediately.

Try it: the Playground

1. Open the Playground and log in.
2. Paste any text as the state.

   Hi, I've been trying to connect my Stripe account for 3 days and it keeps failing. I'm losing sales. Please help ASAP.

3. Add a question. Try a Noul question: "Does this message express urgency?"

   {
     "urgency": {
       "type": "noul",
       "instructions": "Does this message express urgency?"
     }
   }

4. Add more questions. Mix Noul, Choice, and Score in one call and see all results at once.

Call it: the API

1. Get your API key from the dashboard
2. Make a POST request to the API endpoint
3. Review the API Reference for all the details.

   POST https://api.typesafe.ai/v1/systemone
   Authorization: Bearer <API_KEY>
   Content-Type: application/json

Sample cURL command

curl -X POST https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'EOF'
  {
    "state": "Hi, I've been trying to connect my Stripe account for 3 days and it keeps failing. I'm losing sales. Please help ASAP.",
    "model": "jev-latest",
    "questions": {
      "urgency": {
        "type": "noul",
        "instructions": "Does this message express urgency?"
      }
    }
  }
EOF

Request body

   {
     "state": "Hi, I've been trying to connect my Stripe account for 3 days and it keeps failing. I'm losing sales. Please help ASAP.",
     "model": "jev-latest",
     "questions": {
       "department": {
         "type": "choice",
         "instructions": "Which team should handle this",
         "criteria": {
           "billing": "Payment or subscription issues",
           "technical": "Bugs or integration problems",
           "sales": "Pricing or account questions"
         }
       },
       "frustration": {
         "type": "score",
         "instructions": "How frustrated the customer appears",
         "criteria": [
           "Calm, just stating facts",
           "Frustrated but civil",
           "Very angry, strong language"
         ]
       },
       "is_urgent": {
         "type": "noul",
         "instructions": "The message conveys urgency or time-sensitivity"
       }
     }
   }

Response body

   {
     "model": "jev-latest",
     "answers": {
       "department": {
         "type": "choice",
         "choice": "billing",
         "probabilities": {
           "billing": 0.84,
           "technical": 0.159,
           "sales": 0.001
         },
         "confidence": 0.596
       },
       "frustration": {
         "type": "score",
         "score": 1.035,
         "legend": {
           "0": "Calm, just stating facts",
           "1": "Frustrated but civil",
           "2": "Very angry, strong language"
         },
         "confidence": 0.842
       },
       "is_urgent": {
         "type": "noul",
         "noul": 0.999
       }
     },
     "usage": {
       "input_tokens": 312,
       "output_tokens": 48
     }
   }

Code it: the Python SDK

1. Install the SDK (requires Python >= 3.10).

pip install typesafe-sdk

   uv add typesafe-sdk

2. Use the SDK. The client reads TYPESAFE_API_KEY from the environment and calls jev-latest by default.

   from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

client = TypeSafeClient()

ticket = "Hi, I've been trying to connect my Stripe account for 3 days and it keeps failing. I'm losing sales. Please help ASAP."

response = client.system_one(
       state=ticket,
       questions={
           "department": Choice(
               instructions="Which team should handle this",
               criteria={
                   "billing": "Payment or subscription issues",
                   "technical": "Bugs or integration problems",
                   "sales": "Pricing or account questions",
               },
           ),
           "frustration": Score(
               instructions="How frustrated the customer appears",
               criteria=[
                   "Calm, just stating facts",
                   "Frustrated but civil",
                   "Very angry, strong language",
               ],
           ),
           "is_urgent": Noul(
               instructions="The message conveys urgency or time-sensitivity",
           ),
       },
   )

print(response.answers["department"].choice)  # "billing"
   print(response.answers["frustration"].score)  # 1.035
   print(response.answers["is_urgent"].noul)     # 0.999

Vibe it: the agent skill

1. Install the TypeSafe skill using the Claude Code plugin or npx skills add typesafe-ai/skills --skill typesafe-ai. You can also read SKILL.md on GitHub.

2. Tell your coding agent to use the TypeSafe skill as you build!

   Let's build a simple CLI that uses the TypeSafe API to evaluate a set of supplied documents on multiple dimensions. Use the TypeSafe skill to understand how to use the TypeSafe API and how to structure the system. Ask me questions about what kinds of documents I want to evaluate and on what dimensions.