Cortensor Portal V1 Detailed Spec 10 - Docs / Developer Experience
Status
Draft
Purpose
This document defines the developer onboarding and documentation responsibilities for Portal V1.
Portal V1 should not only let a user create a key, it should help them use it immediately.
This spec focuses on:
what documentation should exist in V1
where it should live
what the first developer journey should feel like
how Portal should reduce time from sign-in to first successful request
1. Summary
Portal V1 needs a lightweight but effective developer experience layer.
At minimum, a user should be able to:
understand what the Portal API is
create a key
find a working example request
know where to see usage and limits
Portal V1 does not need a huge docs platform on day one, but it does need enough guidance to make the hosted API feel complete and usable.
2. Goals
Portal V1 docs and developer experience should aim to:
reduce time from sign-in to first successful API request
make the product feel complete and usable
prevent the key page from becoming a dead end
provide enough clarity that a developer can self-serve basic setup
keep the first release simple while leaving room for richer docs later
3. Recommended V1 Docs Surface
Portal should provide a small quick-start docs surface that includes:
base API URL
auth header format
example curl request
where to create API keys
basic model alias examples
link to fuller reference docs if maintained elsewhere
Why this matters
A user who just created an API key should not have to guess:
where to send requests
how to authenticate
which model names are valid
how to know whether they are hitting limits
The quick-start surface should answer those questions immediately.
4. Key Developer Journey
The most important V1 developer journey is:
sign in
create API key
copy key
open docs or quick-start
make first request
return to usage page later
If Portal V1 supports that flow well, the core developer experience is already strong.
Design principle
The developer experience should feel like:
“create key → copy example → make first request”
not like:
“create key → leave Portal → search around → guess how to call API”
5. Documentation Priorities
The highest-priority content for V1 is:
how to authenticate
how to call the hosted API
what model names are supported
what common error responses mean
how usage and limits work at a basic level
This should be treated as the minimum viable docs layer.
Nice-to-have later
Later versions may add:
SDK examples
more detailed model reference
richer error reference
usage / billing troubleshooting
versioned API docs
agent/delegation-specific hosted examples if the Portal grows that way
These should not block V1.
6. Recommended Docs Content for V1
The quick-start docs should ideally include the following sections.
6.1 What the Portal API Is
A very short explanation of:
what the hosted API provides
what the Portal key is used for
that users are calling a hosted Cortensor API, not a raw router directly
The explanation should stay productized and simple.
6.2 Authentication
Users should be shown:
the required auth header format
where to find or create their API key
a short reminder that the raw secret is only shown once
This is one of the highest-value sections because authentication is the first point of friction.
6.3 Base API URL
The docs should clearly show:
the Portal API base URL
whether versioning is in the path
the canonical endpoint shape for V1
This should be visible without requiring the user to click around too much.
6.4 Example Request
At least one working example should exist in V1, ideally a simple curl request.
This should show:
auth header
model parameter
request body
where the response comes back
The example should be easy to copy and modify.
6.5 Supported Models
Portal should show at least a basic list of supported model aliases.
This can be:
a short section on the docs page, or
a linked model reference page later
The user should not need to guess which product-facing model names exist.
6.6 Usage & Limits
The docs should also explain, at a basic level:
that usage is tracked
that limits/reset windows apply
where users can view their usage in the Portal
This helps connect the API experience back to the Portal dashboard.
7. UX Placement
Docs can exist as:
a dedicated
Docspage in the left navigation, ora very visible quick-start section linked from
API KeysorUsage
Recommendation
Some docs presence should exist inside the Portal itself.
That means a user should be able to go from:
created key
to working example
without needing to leave the Portal entirely.
Good V1 pattern
A strong V1 UX pattern would be:
key created successfully
user immediately sees:
copy key
quick-start link
example request link
That makes the key page feel actionable rather than dead-ended.
8. Docs and API Keys Relationship
The docs and API key pages should work together closely.
Desired behavior
After key creation, the Portal should help the user understand:
where the key is used
how to place it in the auth header
where to try the first request
where to check usage after making requests
Product principle
The API key flow should lead naturally into the docs flow.
Not:
create key
stop
But:
create key
learn how to use it
make first request
This relationship is one of the most important DX details in V1.
9. Error Communication
Docs should help users understand common failure cases such as:
invalid key
revoked key
limit reached
model not available
generic backend failure
The goal is not a full exhaustive error encyclopedia in V1.
The goal is to provide enough clarity to prevent obvious confusion.
Recommended style
Use:
plain-language explanations
short examples of what the error means
simple next steps where possible
For example:
invalid key → check auth header or create a new key
revoked key → create a new key and update your client
limit reached → check usage page and reset timing
model not available → verify plan access or supported model list
10. Docs Surface Scope for V1
Portal V1 docs should stay intentionally small.
In scope
quick-start guide
auth header example
example request
base URL
model alias examples
usage / limit explanation
common error explanation
Likely in scope if simple enough
short response example
small FAQ section
tiny “next steps” section
links to broader Cortensor docs
Out of scope unless needed later
huge OpenAPI reference surface
exhaustive SDK library docs
advanced routing docs
deep infrastructure explanations
internal network/session topology explanations
11. Open Questions
Open questions for later refinement:
should the initial docs be embedded in Portal or mostly linked out?
should model reference be a separate page or a small section?
how much API reference detail is needed at launch?
should the first request example be on the
Docspage only, or also shown right after key creation?how much error documentation is enough for V1?
These should be answered with a bias toward:
low friction
minimal scope
fast first success for developers
12. Relationship To Other Specs
This spec connects directly to:
01-ui-ux-web-app.md03-api-key-management.md04-free-plan-rate-limits-and-gateway.md07-router-pools-and-model-product-layer.md08-usage-metering-and-billing.md
It also depends on:
final API shape and base URL decisions
model alias decisions
auth header and key behavior
usage / limit semantics
13. Working Summary
Portal V1 should include a small but effective developer experience layer.
At minimum, a developer should be able to:
sign in
create a key
copy a working example
make a first request
understand where to check usage later
In one sentence:
Portal V1 docs and developer experience should make the path from “signed in” to “first successful API request” feel fast, obvious, and self-serve.
Last updated