# Set the calling tenant's research brief (description + optional website/appStoreUrl/competitors seeds) (/docs/api-reference/v1/workspace/post)

`POST https://api.viralquery.com/v1/workspace`

Set the calling tenant's research brief (description + optional website/appStoreUrl/competitors seeds)

Operation ID: `setWorkspace`

OpenAPI document: https://viralquery.com/openapi.json

## Authentication

Bearer token: `Authorization: Bearer $VIRALQUERY_API_KEY`

## Request

### Request body — application/json (required)

```json
{
  "allOf": [
    {
      "type": "object",
      "properties": {
        "description": {
          "type": "string",
          "minLength": 1,
          "maxLength": 20000
        },
        "website": {
          "type": "string",
          "maxLength": 2048,
          "format": "uri",
          "description": "Public HTTPS website URL; private, loopback, credentialed, and non-HTTPS URLs are rejected."
        },
        "appStoreUrl": {
          "type": "string",
          "maxLength": 2048,
          "format": "uri",
          "description": "Public Apple App Store HTTPS URL containing a numeric app ID."
        },
        "competitors": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 300
          },
          "maxItems": 20
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        "url": {
          "type": "string",
          "maxLength": 2048,
          "format": "uri",
          "description": "Deprecated compatibility alias. Must be a public HTTPS website or Apple App Store URL with a numeric app ID; send website or appStoreUrl instead.",
          "deprecated": true
        }
      },
      "additionalProperties": false,
      "description": "At least one of description, website, appStoreUrl, or deprecated url is required."
    },
    {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "description": {
              "type": "string"
            }
          },
          "required": [
            "description"
          ]
        },
        {
          "type": "object",
          "properties": {
            "website": {
              "type": "string"
            }
          },
          "required": [
            "website"
          ]
        },
        {
          "type": "object",
          "properties": {
            "appStoreUrl": {
              "type": "string"
            }
          },
          "required": [
            "appStoreUrl"
          ]
        },
        {
          "type": "object",
          "properties": {
            "url": {
              "type": "string"
            }
          },
          "required": [
            "url"
          ]
        }
      ]
    }
  ],
  "description": "At least one of description, website, appStoreUrl, or deprecated url is required."
}
```

## Responses

### `200` — OK

**application/json**

```json
{
  "type": "object",
  "properties": {
    "outcome": {
      "type": "string",
      "enum": [
        "created",
        "existing"
      ]
    },
    "workspace": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "description": {
          "type": "string",
          "nullable": true
        },
        "website": {
          "type": "string",
          "nullable": true
        },
        "appStoreUrl": {
          "type": "string",
          "nullable": true
        },
        "competitors": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "subjectType": {
          "type": "string",
          "nullable": true,
          "enum": [
            "app_store",
            "website"
          ]
        },
        "subjectUrl": {
          "type": "string",
          "nullable": true
        },
        "canonicalId": {
          "type": "string",
          "nullable": true
        },
        "name": {
          "type": "string",
          "nullable": true
        },
        "status": {
          "type": "string",
          "enum": [
            "active"
          ]
        },
        "rulesVersion": {
          "type": "integer",
          "minimum": 0
        },
        "createdAt": {
          "type": "number"
        },
        "updatedAt": {
          "type": "number"
        }
      },
      "required": [
        "id",
        "description",
        "website",
        "appStoreUrl",
        "competitors",
        "subjectType",
        "subjectUrl",
        "canonicalId",
        "name",
        "status",
        "rulesVersion",
        "createdAt",
        "updatedAt"
      ]
    }
  },
  "required": [
    "outcome",
    "workspace"
  ]
}
```

### `400` — Invalid request (input failed validation)

**application/json**

```json
{
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "enum": [
            "invalid_request"
          ],
          "description": "Stable machine-readable error code."
        },
        "message": {
          "type": "string",
          "description": "Human-readable summary."
        },
        "issues": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "path": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "path",
              "message"
            ]
          },
          "description": "First-class Zod validation issues (path + message), not a stringified blob."
        }
      },
      "required": [
        "error",
        "message",
        "issues"
      ]
    },
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "enum": [
            "invalid_workspace_brief"
          ]
        },
        "message": {
          "type": "string"
        }
      },
      "required": [
        "error",
        "message"
      ]
    }
  ]
}
```

### `401` — Unauthorized (missing or invalid API key)

**application/json**

```json
{
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "enum": [
            "unauthorized"
          ]
        },
        "message": {
          "type": "string"
        },
        "subscribeUrl": {
          "type": "string",
          "description": "Human-clickable ViralQuery pricing and subscription URL."
        }
      },
      "required": [
        "error",
        "message",
        "subscribeUrl"
      ]
    },
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "enum": [
            "auth_required"
          ]
        },
        "message": {
          "type": "string",
          "description": "The session-scoped key is expired or no longer resolves to its account."
        }
      },
      "required": [
        "error",
        "message"
      ]
    }
  ]
}
```

### `402` — Payment Required (active subscription required)

**application/json**

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "subscription_required"
      ]
    },
    "message": {
      "type": "string"
    },
    "subscribeUrl": {
      "type": "string",
      "description": "Human-clickable ViralQuery pricing and subscription URL."
    }
  },
  "required": [
    "error",
    "message",
    "subscribeUrl"
  ]
}
```

### `403` — Forbidden (scope or plan is insufficient)

**application/json**

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "forbidden"
      ]
    },
    "message": {
      "type": "string"
    },
    "requiredScope": {
      "type": "string",
      "description": "Scope or explicit session capability required by this operation."
    },
    "grantedScopes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Scopes present on the calling key."
    }
  },
  "required": [
    "error",
    "message",
    "requiredScope",
    "grantedScopes"
  ]
}
```

### `409` — Conflict or operation error

**application/json**

```json
{
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "enum": [
            "workspace_already_set"
          ]
        },
        "message": {
          "type": "string"
        },
        "workspace": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "description": {
              "type": "string",
              "nullable": true
            },
            "website": {
              "type": "string",
              "nullable": true
            },
            "appStoreUrl": {
              "type": "string",
              "nullable": true
            },
            "competitors": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "subjectType": {
              "type": "string",
              "nullable": true,
              "enum": [
                "app_store",
                "website"
              ]
            },
            "subjectUrl": {
              "type": "string",
              "nullable": true
            },
            "canonicalId": {
              "type": "string",
              "nullable": true
            },
            "name": {
              "type": "string",
              "nullable": true
            },
            "status": {
              "type": "string",
              "enum": [
                "active"
              ]
            },
            "rulesVersion": {
              "type": "integer",
              "minimum": 0
            },
            "createdAt": {
              "type": "number"
            },
            "updatedAt": {
              "type": "number"
            }
          },
          "required": [
            "id",
            "description",
            "website",
            "appStoreUrl",
            "competitors",
            "subjectType",
            "subjectUrl",
            "canonicalId",
            "name",
            "status",
            "rulesVersion",
            "createdAt",
            "updatedAt"
          ]
        }
      },
      "required": [
        "error",
        "message",
        "workspace"
      ]
    },
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "enum": [
            "operation_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "The operation failed while handling the request."
        }
      },
      "required": [
        "error",
        "message"
      ]
    }
  ]
}
```

### `429` — Too Many Requests (rate limited)

**application/json**

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "rate_limited"
      ]
    },
    "message": {
      "type": "string"
    },
    "retryAfter": {
      "type": "number",
      "description": "Seconds to wait before retrying (mirrors the Retry-After header)."
    }
  },
  "required": [
    "error",
    "message",
    "retryAfter"
  ]
}
```