Skip to Content
Launching the open-source gateway

Get a custom model

GEThttps://api.respan.ai/api/models/{model_name}/

Retrieve a custom model by model name. Custom models are only visible to the project that owns them.

Servers

https://api.respan.ai — Respan API Server

Authentication

RespanApiKey

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.

HTTP scheme: bearer; format: Respan API key.

Authorization: Bearer $RESPAN_API_KEY

Or:

DashboardJwt

Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.

HTTP scheme: bearer; format: Dashboard JWT.

Authorization: Bearer $RESPAN_DASHBOARD_JWT

Path parameters

Parameter Type Required Description and constraints
model_name string Required
The model_name that List models returns. Built-in models are provider-prefixed, such as openai/gpt-4o-mini; bare names such as gpt-4o-mini return 404.

Responses

200

Model details.

application/json

Field Type Requirement Description and constraints
$ object Body
Additional properties are allowed
id string Required in parent
Model string ID. Same value as model_name.
Example: "my-custom-gpt-4o"
model_name string Required in parent
Model name used in API calls.
Example: "my-custom-gpt-4o"
base_model_name string Optional
Base model inherited from, when configured.
Example: "gpt-4o"
affiliation_category string Optional
keywordsai for built-in models, custom for your organization’s models.
Allowed: "keywordsai", "custom"
Example: "custom"
is_called_by_custom_name boolean Optional
Whether requests are sent upstream using this custom model name.
Example: false
input_cost number Optional
Cost per 1M input tokens in USD.
Example: 2.5
output_cost number Optional
Cost per 1M output tokens in USD.
Example: 10
cache_hit_input_cost number Optional
Cost per 1M cached input tokens in USD.
Example: 0.5
cache_creation_input_cost number Optional
Cost per 1M cache creation input tokens in USD.
Example: 3
max_context_window integer Optional
Maximum context window size.
Example: 128000
function_call integer Optional
Function/tool calling support. 0 = no, 1 = yes.
Allowed: 0, 1
Example: 1
image_support integer Optional
Vision input support. 0 = no, 1 = yes.
Allowed: 0, 1
Example: 1
model_type string Optional
Model type.
Allowed: "chat", "embedding", "audio"
Example: "chat"
supported_params object Optional
Computed parameter support after applying model-specific overrides.
Additional properties are allowed
provider object or null Optional
Additional properties are allowed
provider.id string Required in parent
Provider string ID. Same value as provider_id.
Example: "my-vllm"
provider.provider_id string Required in parent
Unique provider identifier within your organization.
Example: "my-vllm"
provider.provider_name string Required in parent
Human-readable provider name.
Example: "My vLLM Server"
provider.extra_kwargs object Optional
Provider configuration such as base_url and timeout values. Secret values are not returned here.
Additional properties are allowed
Example: {"base_url":"https://vllm.example.com/v1"}
provider.created_at string or null Optional
Format: date-time
provider.updated_at string or null Optional
Format: date-time

OpenAPI response schema

{
  "type": "object",
  "required": [
    "id",
    "model_name"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Model string ID. Same value as `model_name`.",
      "example": "my-custom-gpt-4o"
    },
    "model_name": {
      "type": "string",
      "description": "Model name used in API calls.",
      "example": "my-custom-gpt-4o"
    },
    "base_model_name": {
      "type": "string",
      "description": "Base model inherited from, when configured.",
      "example": "gpt-4o"
    },
    "affiliation_category": {
      "type": "string",
      "description": "`keywordsai` for built-in models, `custom` for your organization's models.",
      "enum": [
        "keywordsai",
        "custom"
      ],
      "example": "custom"
    },
    "is_called_by_custom_name": {
      "type": "boolean",
      "description": "Whether requests are sent upstream using this custom model name.",
      "example": false
    },
    "input_cost": {
      "type": "number",
      "description": "Cost per 1M input tokens in USD.",
      "example": 2.5
    },
    "output_cost": {
      "type": "number",
      "description": "Cost per 1M output tokens in USD.",
      "example": 10
    },
    "cache_hit_input_cost": {
      "type": "number",
      "description": "Cost per 1M cached input tokens in USD.",
      "example": 0.5
    },
    "cache_creation_input_cost": {
      "type": "number",
      "description": "Cost per 1M cache creation input tokens in USD.",
      "example": 3
    },
    "max_context_window": {
      "type": "integer",
      "description": "Maximum context window size.",
      "example": 128000
    },
    "function_call": {
      "type": "integer",
      "enum": [
        0,
        1
      ],
      "description": "Function/tool calling support. `0` = no, `1` = yes.",
      "example": 1
    },
    "image_support": {
      "type": "integer",
      "enum": [
        0,
        1
      ],
      "description": "Vision input support. `0` = no, `1` = yes.",
      "example": 1
    },
    "model_type": {
      "type": "string",
      "description": "Model type.",
      "enum": [
        "chat",
        "embedding",
        "audio"
      ],
      "example": "chat"
    },
    "supported_params": {
      "type": "object",
      "description": "Computed parameter support after applying model-specific overrides.",
      "additionalProperties": true
    },
    "provider": {
      "type": "object",
      "required": [
        "id",
        "provider_id",
        "provider_name"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Provider string ID. Same value as `provider_id`.",
          "example": "my-vllm"
        },
        "provider_id": {
          "type": "string",
          "description": "Unique provider identifier within your organization.",
          "example": "my-vllm"
        },
        "provider_name": {
          "type": "string",
          "description": "Human-readable provider name.",
          "example": "My vLLM Server"
        },
        "extra_kwargs": {
          "type": "object",
          "description": "Provider configuration such as `base_url` and timeout values. Secret values are not returned here.",
          "additionalProperties": true,
          "example": {
            "base_url": "https://vllm.example.com/v1"
          }
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        }
      },
      "additionalProperties": true,
      "nullable": true
    }
  },
  "additionalProperties": true
}

403

The API key is missing, invalid or expired.

application/json

Field Type Requirement Description and constraints
$ object Body
—
detail string Required in parent
—

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Example
{
  "detail": "Your API key is invalid or expired, please check your API key in the platform settings."
}

404

Not Found

application/json

Field Type Requirement Description and constraints
$ object Body
—
detail string Optional
—
error string Optional
—

OpenAPI response schema

{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  }
}
Example
{
  "error": "Not found"
}

OpenAPI source

The operation and referenced components below retain the complete OpenAPI definitions, including constraints and examples.

OpenAPI operation

{
  "summary": "Get a custom model",
  "operationId": "retrieveCustomModel",
  "tags": [
    "Models"
  ],
  "description": "Retrieve a custom model by model name. Custom models are only visible to the project that owns them.",
  "parameters": [
    {
      "name": "model_name",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "The `model_name` that List models returns. Built-in models are provider-prefixed, such as `openai/gpt-4o-mini`; bare names such as `gpt-4o-mini` return 404."
    }
  ],
  "responses": {
    "200": {
      "description": "Model details.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "id",
              "model_name"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "Model string ID. Same value as `model_name`.",
                "example": "my-custom-gpt-4o"
              },
              "model_name": {
                "type": "string",
                "description": "Model name used in API calls.",
                "example": "my-custom-gpt-4o"
              },
              "base_model_name": {
                "type": "string",
                "description": "Base model inherited from, when configured.",
                "example": "gpt-4o"
              },
              "affiliation_category": {
                "type": "string",
                "description": "`keywordsai` for built-in models, `custom` for your organization's models.",
                "enum": [
                  "keywordsai",
                  "custom"
                ],
                "example": "custom"
              },
              "is_called_by_custom_name": {
                "type": "boolean",
                "description": "Whether requests are sent upstream using this custom model name.",
                "example": false
              },
              "input_cost": {
                "type": "number",
                "description": "Cost per 1M input tokens in USD.",
                "example": 2.5
              },
              "output_cost": {
                "type": "number",
                "description": "Cost per 1M output tokens in USD.",
                "example": 10
              },
              "cache_hit_input_cost": {
                "type": "number",
                "description": "Cost per 1M cached input tokens in USD.",
                "example": 0.5
              },
              "cache_creation_input_cost": {
                "type": "number",
                "description": "Cost per 1M cache creation input tokens in USD.",
                "example": 3
              },
              "max_context_window": {
                "type": "integer",
                "description": "Maximum context window size.",
                "example": 128000
              },
              "function_call": {
                "type": "integer",
                "enum": [
                  0,
                  1
                ],
                "description": "Function/tool calling support. `0` = no, `1` = yes.",
                "example": 1
              },
              "image_support": {
                "type": "integer",
                "enum": [
                  0,
                  1
                ],
                "description": "Vision input support. `0` = no, `1` = yes.",
                "example": 1
              },
              "model_type": {
                "type": "string",
                "description": "Model type.",
                "enum": [
                  "chat",
                  "embedding",
                  "audio"
                ],
                "example": "chat"
              },
              "supported_params": {
                "type": "object",
                "description": "Computed parameter support after applying model-specific overrides.",
                "additionalProperties": true
              },
              "provider": {
                "type": "object",
                "required": [
                  "id",
                  "provider_id",
                  "provider_name"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "Provider string ID. Same value as `provider_id`.",
                    "example": "my-vllm"
                  },
                  "provider_id": {
                    "type": "string",
                    "description": "Unique provider identifier within your organization.",
                    "example": "my-vllm"
                  },
                  "provider_name": {
                    "type": "string",
                    "description": "Human-readable provider name.",
                    "example": "My vLLM Server"
                  },
                  "extra_kwargs": {
                    "type": "object",
                    "description": "Provider configuration such as `base_url` and timeout values. Secret values are not returned here.",
                    "additionalProperties": true,
                    "example": {
                      "base_url": "https://vllm.example.com/v1"
                    }
                  },
                  "created_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                  },
                  "updated_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                  }
                },
                "additionalProperties": true,
                "nullable": true
              }
            },
            "additionalProperties": true
          }
        }
      }
    },
    "403": {
      "$ref": "#/components/responses/InvalidApiKey"
    },
    "404": {
      "description": "Not Found",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "detail": {
                "type": "string"
              },
              "error": {
                "type": "string"
              }
            }
          },
          "example": {
            "error": "Not found"
          }
        }
      }
    }
  },
  "security": [
    {
      "RespanApiKey": []
    },
    {
      "DashboardJwt": []
    }
  ]
}

OpenAPI path metadata

{}

Referenced OpenAPI components

{
  "responses": {
    "InvalidApiKey": {
      "description": "The API key is missing, invalid or expired.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "detail"
            ],
            "properties": {
              "detail": {
                "type": "string"
              }
            }
          },
          "example": {
            "detail": "Your API key is invalid or expired, please check your API key in the platform settings."
          }
        }
      }
    }
  },
  "securitySchemes": {
    "DashboardJwt": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Dashboard JWT",
      "description": "Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.",
      "x-fern-bearer": {
        "name": "dashboardJwt",
        "env": "RESPAN_DASHBOARD_JWT"
      }
    },
    "RespanApiKey": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Respan API key",
      "description": "Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.",
      "x-fern-bearer": {
        "name": "respanApiKey",
        "env": "RESPAN_API_KEY"
      }
    }
  }
}