Add inputs

How to turn a cell of your workbook into an input of the service: selecting the cell, the fields of the dialog, and what SpreadAPI fills in for you.

1:15

What an input is

An input is one cell of the workbook that a caller may set. With each call the caller sends a value for the input, SpreadAPI writes it into the cell, and the workbook calculates with it. Typical inputs are an amount, an interest rate, a product name or a yes/no option.

An input is always a single cell that holds a plain value, not a formula.

Add an input

1. Open the service on the Configuration (Konfiguration) tab. The panel on the right shows the tab Parameters (Parameter) with the lists Input Parameters (Eingabe-Parameter) and Output Parameters (Ausgabe-Parameter).
2. Click the cell in the workbook. The box at the bottom of the panel shows its address, for example Sheet1!B2, and the badge IN.
3. Click Add as Parameter (Als Parameter hinzufügen). The dialog Add Input Parameter (Eingabe-Parameter hinzufügen) opens.
4. Check the suggested fields (next section) and change what does not fit.
5. Click Add Parameter (Parameter hinzufügen). The input appears under Input Parameters with its name and address.
6. Click Save (Speichern). To make the input available to callers, publish the service; see Publish and republish.

The badge tells you what the selected cell will become: IN for a single cell with a plain value, OUT for a cell with a formula or for a range. Outputs are described in Add outputs.

The fields of the dialog

The dialog has two views: Parameter Info and AI Info (KI Info).

Parameter Info

The rules behind minimum, maximum, allowed values, required and default are explained in Input validation.

AI Info

Good texts here decide how well an AI assistant fills in the input; see Write good descriptions.

What SpreadAPI fills in for you

When the dialog opens, most fields already have a value taken from the workbook:

• Title and name come from the text label next to the cell. SpreadAPI looks up to four cells to the left, then up to four cells above. The label "Loan amount" gives the title "Loan amount" and the name loan_amount. Without a label the name is the cell address, for example b2.
• Data type comes from the value in the cell: a number gives Number, TRUE or FALSE gives Boolean, anything else String.
• Percentage. A cell formatted as a percentage becomes a percentage input, with minimum 0, maximum 1, the display format of the cell and example values such as "0.05 for 5%". See Percentages and formats.
• Allowed values. A cell with a drop-down list gets its list entries as allowed values. The dialog says Auto-detected from cell dropdown with the number of items.
• Default. When you make the input optional, the current value of the cell is suggested as the default.

Names

• The dialog stores names in lower case.
• Use lower-case letters, digits and _, and start with a letter or _: amount, tax_rate, years_2.
• Give every input its own name.
• Callers send the value under this name. Choose it carefully before you publish; changing it later affects callers, see Rename, reorder and remove parameters.

Required or optional

A new input is required: Mandatory parameter is ticked. A call that does not send it is refused with "Missing required parameters". In the list, a required input carries a red * after its name.

Untick Mandatory parameter to make the input optional. The field Default Value (Optional) then appears. A caller who leaves the input out gets a calculation with this default. If you leave the default empty, the cell is empty for that call.

Rules

• One cell. An input is a single cell. A range is offered as an output.
• No formula. A cell with a formula is offered as an output. To let callers override a calculated value, give the value its own input cell and let the formula read from it.
• One parameter per cell. A cell that already is a parameter shows Already added (Bereits hinzugefügt), and a selection that overlaps an existing parameter is refused.

Change or remove an input

Hover over the input in the list. The pencil opens the dialog again; the bin removes the input after a confirmation. Clicking the input jumps to its cell. Drag the handle on the left to change the order. See Rename, reorder and remove parameters.

For developers and agents

A caller sends inputs by name:

GET https://spreadapi.io/api/v1/services/{serviceId}/execute?loan_amount=200000&annual_rate=0.04&years=20

POST https://spreadapi.io/api/v1/services/{serviceId}/execute

{ "inputs": { "loan_amount": 200000, "annual_rate": 0.04, "years": 20 } }

• Names are not case-sensitive for callers: Loan_Amount and loan_amount are the same input.
• A key that matches no input is ignored.
• The answer repeats the inputs that were used as inputs: a list of { "name", "title", "value" }. See The API response.
• An AI agent connected to the account defines inputs by cell address and lets the rest be read from the workbook; see Build a service with an agent.

FAQ

How do I add an input to my service?

On the Configuration tab, click the cell, then click Add as Parameter at the bottom of the panel on the right. Check the name and type in the dialog, click Add Parameter, then Save.

Why is "Add as Parameter" greyed out?

Either no cell is selected, or the selected cell already is a parameter; the box above the button then shows No cell selected or Already added. Click another cell.

Why does my cell show OUT instead of IN?

The cell holds a formula, or you selected more than one cell. Formula cells and ranges become outputs; an input is a single cell with a plain value.

How do I make an input optional?

Open the input with the pencil, untick Mandatory parameter, and set Default Value (Optional) if the calculation needs a value. Click Update Parameter, save and publish again.

What is the difference between the name and the title?

The name is the technical key callers send, such as loan_amount. The title is the readable label, such as "Loan amount", shown to people and AI assistants and returned with each answer.

Where does the suggested name come from?

From the text label next to the cell: SpreadAPI looks up to four cells to the left, then up to four cells above. Without a label it uses the cell address, for example b2.

Can a range of cells be an input?

No. An input is a single cell. Add each cell as its own input, or keep a table inside the workbook and let callers choose a row with one input and a lookup formula.

Can I use the same cell as input and output?

No. A cell can be one parameter only. To return an input value in the outputs, add a formula cell that references it, for example =B2, as an output; the answer also repeats the inputs under inputs.

How many inputs can a service have?

There is no fixed number in the panel. Keep to the values a caller really needs to set; everything else can stay a fixed value in the workbook.

As an agent, which name do I use to send a value?

Use the input's name, in lower case, as the key: as a query parameter for GET or inside "inputs" for POST. The service's definition lists every input with its name, type and rules.