Server updates
How service metadata is registered, stored, and updated on the Socaity backend — and when you, as an SDK user, need to think about it.
Every service you can call from the SDK has metadata living on the Socaity backend — a description, the list of endpoints, where the service is hosted, and which model backs it. When that metadata changes, a server update is the process that propagates the change to the database the SDK reads from.
The database is the source of truth after a service is first registered. The service's openapi.json is the source of truth for endpoint parameter schemas only.
| Table | What it holds |
|---|---|
service_descriptors | Canonical metadata for a service — name, description, and human-readable info. One row per logical service. |
service_hosting_information | Where and how a service is deployed. Multiple hosting records can exist per service (e.g. regions, providers, private deployments). |
service_endpoints | Endpoint metadata per service (name, description). Parameter schemas live in the service's openapi.json. |
service_categories | Many-to-many classification (Image Generation, Chat, Text-to-Image…). |
ServiceFamily | Groups closely related variants under a shared family (e.g. multiple Flux-Schnell deployments with minor differences). |
ServiceCollection | Curator-managed groupings (e.g. all Meta/Facebook models). Many-to-many. |
model_descriptors | Documents the underlying AI model(s) backing a service. A service can use more than one model. |
When a service is first added to the platform, the openapi.json is the seed:
- The descriptor and endpoint metadata are populated from the OpenAPI spec — docstrings and the APIPod
Appmetadata. - An LLM enrichment pass runs to standardise and improve the description.
- From that point on, the database is the ground truth. Descriptions can be edited directly; the
openapi.jsonis no longer the primary source for descriptive content. - Endpoint parameter schemas remain tied to
openapi.jsonat all times.
An update is triggered when the repository a service was built from publishes a new release. It is distinct from a re-upload — it propagates automatically to all deployments linked to that repository.
- The new
openapi.jsonis diffed against the current state. - An LLM merge pass reconciles the existing database description with any new information from the spec — the goal is to keep the richer of the two, not blindly overwrite.
- The merged result is written back to the database.
| Scenario | What happens |
|---|---|
Identical openapi.json re-uploaded | You are asked whether to create a private deployment. If you decline, nothing is written. |
Modified openapi.json uploaded | Treated as an entirely new service. A fresh descriptor, hosting record, and endpoints are created from scratch. |
| Repository releases a new version | In-place update via the LLM merge flow. Propagates to all public deployments linked to the repo. |
| If you are | Then |
|---|---|
| Calling official services from the SDK | You do not need to think about this. Updates are propagated for you. |
| Publishing a service from APIPod | Cut a new release of your repo to trigger an in-place update. Modify the spec meaningfully and a re-upload creates a new service. |
| Running a private deployment | Your copy is isolated from upstream changes. Re-deploy explicitly when you want a newer version. |
Socaity proxies third-party providers such as Replicate. Their URL shape and update behaviour differ from Socaity-hosted services.
| Provider | URL pattern |
|---|---|
| Socaity-hosted | services/{user_name}/{service_name}/{endpoint_name} |
| Replicate | services/third-party/replicate/{user}/{model}/predictions |
Third-party services are read-only on the Socaity side: you can call them, but Socaity cannot redeploy or rehost them.
service_data_readme.md in the Socaity backend repo. See that file for the latest, most detailed reference.