API Testing Tools and Agent Readiness: How Postman, Insomnia, and curl Verify Your Score
You do not need a specialized scanner to understand your agent readiness. The tools you already use — Postman, Insomnia, and curl — can test the five things that matter most. Here is the exact workflow, with commands you can run right now.
The 5-Step Agent Readiness Testing Workflow
When an AI agent evaluates your API for the first time, it runs through a predictable sequence: check health, test authentication, probe error handling, look for rate limits, and search for a spec. You can simulate this entire sequence with five curl commands. Each step maps directly to a dimension in the Agent Readiness Score.
Health check
Verify the API is alive and returning structured responses. An agent's first interaction is always a health or discovery check.
curl -s https://api.example.com/health | jq .
Expected result: 200 OK with JSON body: { "status": "healthy", "version": "2.1.0" }
Authentication
Test that auth returns proper 401 with JSON error body (not HTML). Agents need machine-readable rejection to handle auth flows programmatically.
curl -s -o /dev/null -w "%{http_code}" https://api.example.com/protected
curl -s -H "Authorization: Bearer invalid_token" https://api.example.com/protected | jq .Expected result: 401 with JSON: { "error": "unauthorized", "message": "...", "code": "AUTH_REQUIRED" }
Error responses
Send malformed requests and verify errors come back as structured JSON with error codes — not HTML 500 pages or stack traces.
curl -s -X POST https://api.example.com/orders -H "Content-Type: application/json" -d '{"invalid": true}' | jq .Expected result: 400 with JSON: { "error": "validation_error", "fields": [{ "field": "items", "message": "required" }] }
Rate limit headers
Check for X-RateLimit-Limit, X-RateLimit-Remaining, and Retry-After headers. Agents use these to throttle requests and avoid bans.
curl -s -D - https://api.example.com/products 2>&1 | grep -i "rate\|retry\|x-ratelimit"
Expected result: Headers present: X-RateLimit-Limit: 100, X-RateLimit-Remaining: 99, X-RateLimit-Reset: 1714000000
OpenAPI spec
Check if a machine-readable API specification exists. This is how agents auto-discover all available endpoints and their schemas.
curl -s https://api.example.com/openapi.json | jq '.info.title, .paths | keys[:5]'
Expected result: Valid OpenAPI 3.x document with paths, schemas, and descriptions for every endpoint.
10 curl Commands That Predict Your Score
Each of these commands tests a specific aspect of your agent readiness. Run them against your own domain and compare the results with what the agent readiness checklist recommends. Together they cover the highest-weighted scoring dimensions.
1. Check for agent-card.json
curl -s https://example.com/.well-known/agent-card.json | jq .
Impact: D9 Agent Experience: +15 points if present and valid
2. Check for llms.txt
curl -s https://example.com/llms.txt | head -20
Impact: D9 Agent Experience: +10 points if present
3. Check for OpenAPI spec
curl -s https://example.com/openapi.json | jq .info
Impact: D2 API Quality: +20 points if valid spec exists
4. Test JSON error handling
curl -s -X DELETE https://example.com/api/nonexistent | jq .
Impact: D8 Reliability: +12 points for structured error responses
5. Check CORS headers
curl -s -H "Origin: https://agent.example.com" -D - https://example.com/api/health 2>&1 | grep -i "access-control"
Impact: D7 Security: +5 points for proper CORS configuration
6. Check TLS certificate
curl -vI https://example.com 2>&1 | grep "SSL\|TLS\|certificate"
Impact: D7 Security: Hard cap at 39/100 without TLS
7. Check response time
curl -s -o /dev/null -w "time_total: %{time_total}s\n" https://example.com/api/healthImpact: D8 Reliability: Sub-500ms is good, sub-200ms is excellent
8. Check Schema.org markup
curl -s https://example.com | grep -o 'application/ld+json' | wc -l
Impact: D6 Data Quality: +8 points for structured data markup
9. Check robots.txt
curl -s https://example.com/robots.txt | head -10
Impact: D1 Discovery: +3 points, critical for crawler access
10. Check status page
curl -s https://status.example.com | head -5 || echo "No status page"
Impact: D8 Reliability: +5 points for public status endpoint
After running these 10 commands: Head to agenthermes.ai/audit and run the full scan. Compare your manual findings with the automated score. The AgentHermes scanner tests 50+ checks across 9 dimensions, including vertical-specific weighting that these curl commands cannot replicate. But you will already know the major gaps before you scan.
Postman vs Insomnia vs curl for Agent Readiness Testing
All three tools can test your agent readiness, but each has different strengths. The best choice depends on whether you want quick spot checks (curl), visual exploration (Insomnia), or comprehensive automated testing (Postman).
curl
Fastest for single-endpoint checks. Scriptable. Ships with every OS. Ideal for CI/CD pipelines and quick agent-readiness spot checks.
Tests exactly what an agent sees: raw HTTP request and response. No UI abstractions. The closest simulation of an agent's actual experience.
Postman
Import OpenAPI specs to auto-generate test collections. Visual response inspection. Environment variables for staging vs production. Team collaboration on test suites.
Collection Runner can test every endpoint in sequence — mimicking an agent's discovery flow. Pre-request scripts simulate auth token refresh cycles agents perform.
Insomnia
Lightweight alternative to Postman. Native OpenAPI support. Environment switching between test and production. Plugin ecosystem for custom auth flows.
Environment variables let you test the same endpoints against dev, staging, and prod — verifying consistency across environments, which agents expect.
The Postman Agent Readiness Collection
If you have an OpenAPI spec, Postman is the most powerful tool for comprehensive agent readiness testing. Here is the workflow we recommend.
Import your OpenAPI spec
File > Import > paste your openapi.json URL. Postman auto-generates a request for every endpoint with example parameters pre-filled from the schema.
Create environment variables
Set up two environments: "Production" and "Staging." Variables: base_url, api_key, auth_token. This lets you verify that both environments return consistent responses — which agents expect.
Add test scripts to every request
Postman tests verify: response is JSON (pm.response.to.be.json), status code is correct, response time is under 500ms (pm.response.responseTime < 500), and required fields exist in the body.
Run the Collection Runner
Execute all requests in sequence. This simulates an agent discovering your API: first the spec, then auth, then iterating through every endpoint. The runner report shows which requests fail.
Check the results against the checklist
Compare your Collection Runner results with the agent readiness checklist. Every failing request is a dimension score reduction. Fix the failures, re-run, and verify improvement before scanning with AgentHermes.
The key insight is that Postman Collection Runner mimics agent behavior. An AI agent discovering your API goes through the same sequence: fetch spec, authenticate, iterate endpoints, check responses. If your collection passes cleanly in Postman, your API will score well when agents evaluate it. If requests fail, those are exactly the failures agents will encounter.
For businesses that already have an OpenAPI specification, this workflow takes under 30 minutes and gives you a reliable preview of your Agent Readiness Score before you run the official scan.
Frequently Asked Questions
Can I really predict my Agent Readiness Score with curl?
You can approximate 60-70% of your score with the 10 curl commands in this guide. They test the most heavily weighted dimensions: API quality (D2), security (D7), reliability (D8), and agent experience (D9). The remaining 30-40% comes from deeper analysis that AgentHermes performs — like evaluating response schema consistency, documentation quality, and vertical-specific scoring weights. Run the curl tests first, then run the full AgentHermes scan to see the complete picture.
What is the most impactful single test I can run?
Check for an OpenAPI spec: curl -s https://yoursite.com/openapi.json. If this returns a valid OpenAPI 3.x document, your D2 API Quality score jumps significantly. If it returns 404, your API is undiscoverable to agents — they cannot learn what endpoints exist, what parameters they accept, or what responses to expect. The OpenAPI spec is the single highest-leverage artifact for agent readiness.
Should I use Postman or Insomnia?
For agent readiness testing specifically, Postman has an edge because of its Collection Runner and ability to import OpenAPI specs directly. You can import your spec, auto-generate requests for every endpoint, and run the full collection — simulating what an agent does during discovery. Insomnia is lighter and faster for quick manual testing. Both work well. If you have neither, curl covers the critical tests.
How do I test if my error responses are agent-friendly?
Send requests that should fail: missing auth, invalid JSON body, nonexistent resource IDs, wrong HTTP method on an endpoint. For each, check that the response is JSON (not HTML), includes a machine-readable error code (not just a human message), and returns the correct HTTP status code. If any error returns an HTML page or a 200 status with an error message in the body, that is an agent readiness problem. Agents cannot reliably parse HTML error pages.
What does the AgentHermes scan test that curl cannot?
AgentHermes tests 9 dimensions across 50+ checks including: vertical-specific scoring weights (a restaurant is scored differently than a SaaS product), Schema.org structured data parsing, MCP server detection and protocol validation, agent-card.json schema compliance, cross-referencing multiple endpoints for API consistency, documentation quality scoring, and comparison against 500+ scanned businesses. The curl tests cover the binary checks — does this exist or not. AgentHermes evaluates quality and completeness.
Done testing manually? Run the full scan.
The AgentHermes scanner tests 50+ checks across 9 dimensions with vertical-specific scoring. Compare your curl results with the automated score in 60 seconds.